1 介绍
1.1 定义
01.Kratos框架定义
a.基本概念
Kratos是一个Go语言编写的微服务框架，专注于云原生架构和微服务治理，提供完整的微服务开发、部署、监控和运维一体化解决方案。
b.技术定位
a.功能定位
面向企业级微服务应用开发，提供标准化、可扩展、高可用的微服务基础设施平台，支持大规模分布式系统的构建和管理。
b.架构定位
基于Go语言的云原生微服务框架，集成gRPC、HTTP、Protocol Buffers等技术栈，遵循DDD（领域驱动设计）和Clean Architecture原则。
c.生态定位
作为CNCF（云原生计算基金会）生态系统的一部分，与Kubernetes、Prometheus、Jaeger等云原生工具链无缝集成。
c.核心价值
a.开发效率
通过标准化的项目结构、代码生成工具和最佳实践，显著提升微服务开发效率，减少重复性工作。
b.运维友好
内置健康检查、配置管理、日志记录、监控指标等运维特性，使微服务更容易部署、监控和维护。
c.技术先进性
采用现代化技术栈和架构模式，支持容器化部署和云原生架构，适应复杂多变的业务需求。
d.框架特点
a.模块化设计
采用插件化架构，各功能模块相互独立，支持按需引入和自定义扩展，提供灵活的组件组合能力。
b.标准化规范
统一的编码规范、API设计模式和项目结构，确保团队协作的一致性和代码质量。
c.生产级特性
内置熔断、限流、重试、服务发现等生产级特性，满足企业级应用的可靠性要求。
02.框架构成要素
a.核心组件
a.应用生命周期管理
Application组件负责微服务的完整生命周期管理，包括启动、运行、优雅关闭等阶段。
b.服务通信层
Transport层提供gRPC和HTTP两种通信协议支持，实现服务间的高效数据交换。
c.配置管理系统
Config组件支持多种配置源（文件、环境变量、配置中心）的动态加载和热更新。
b.基础设施组件
a.日志系统
Logging组件提供结构化日志记录能力，支持多种输出格式和日志级别控制。
b.监控体系
Metrics组件集成Prometheus，提供丰富的性能指标采集和监控能力。
c.链路追踪
Tracing组件基于OpenTelemetry标准，实现分布式系统的请求链路追踪。
d.Kratos定义示例
---
// Kratos应用的基本定义示例
package main
import (
"context"
"flag"
"os"
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/examples/helloworld/helloworld"
)
// GreeterService 定义服务接口
type GreeterService interface {
SayHello(ctx context.Context, req *helloworld.HelloRequest) (*helloworld.HelloReply, error)
}
// greeterService 实现服务接口
type greeterService struct {
helloworld.UnimplementedGreeterServer
}
// SayHello 实现具体业务逻辑
func (s *greeterService) SayHello(ctx context.Context, req *helloworld.HelloRequest) (*helloworld.HelloReply, error) {
log.Infof("Received greeting request: %v", req.Name)
return &helloworld.HelloReply{
Message: "Hello " + req.GetName(),
}, nil
}
// main 应用入口函数
func main() {
flag.Parse()
logger := log.With(log.NewStdLogger(os.Stdout),
"ts", log.DefaultTimestamp,
"caller", log.DefaultCaller,
"service.id", "helloworld.service",
"service.name", "helloworld",
"service.version", "v1.0.0",
)
// 配置加载
c := config.New(
config.WithSource(
file.NewSource("configs/config.yaml"),
),
)
if err := c.Load(); err != nil {
panic(err)
}
// 创建Kratos应用实例
app := kratos.New(
kratos.ID("helloworld.service"), // 服务ID
kratos.Name("helloworld"), // 服务名称
kratos.Version("v1.0.0"), // 服务版本
kratos.Metadata(map[string]string{}), // 服务元数据
kratos.Logger(logger), // 日志记录器
kratos.Server( // 服务器配置
http.NewServer(
http.Address(":8000"),
),
grpc.NewServer(
grpc.Address(":9000"),
),
),
)
// 注册服务实现
helloworld.RegisterGreeterServer(app.Server(grpc.NewServer()), &greeterService{})
helloworld.RegisterGreeterHTTPServer(app.Server(http.NewServer()), &greeterService{})
// 启动应用
if err := app.Run(); err != nil {
logger.Errorf("application run failed: %v", err)
}
}
---
03.与微服务的关系
a.微服务架构需求
a.服务拆分
Kratos支持单体应用向微服务架构的平滑迁移，提供服务拆分的最佳实践指导。
b.服务治理
内置服务注册发现、负载均衡、熔断限流等服务治理能力，确保微服务系统的稳定性。
c.数据一致性
提供分布式事务、事件溯源等模式，解决微服务架构下的数据一致性问题。
b.Kratos在微服务中的角色
a.开发框架
作为微服务开发的基础设施，提供标准化的开发模式和工具链。
b.运行时平台
为微服务提供运行时环境，管理服务生命周期和依赖关系。
c.治理中心
集成各种治理组件，实现微服务的统一管理和监控。
c.技术优势
a.原生Go支持
充分发挥Go语言的并发性能和编译优势，提供高性能的微服务运行环境。
b.云原生友好
支持容器化部署和Kubernetes编排，适配云原生架构的最佳实践。
c.生态丰富
与Go生态系统深度集成，可以方便地使用各种第三方库和工具。
1.2 核心概念
01.Application概念
a.应用定义
Application是Kratos框架的核心抽象，代表一个完整的微服务应用实例，管理服务的整个生命周期。
b.应用组成
a.基础设施层
包含日志、配置、监控等基础组件，为应用提供运行时支撑能力。
b.传输层
提供HTTP、gRPC等协议支持，处理客户端请求和服务间通信。
c.业务层
包含具体的业务逻辑实现，通过接口定义与传输层解耦。
d.数据层
负责数据持久化、缓存管理等数据处理相关功能。
c.生命周期管理
a.启动阶段
配置加载 → 依赖注入 → 服务注册 → 端口监听 → 健康检查
b.运行阶段
请求处理 → 服务调用 → 状态监控 → 错误恢复
c.关闭阶段
请求等待 → 资源清理 → 服务注销 → 进程退出
02.Transport概念
a.传输层定义
Transport层负责处理网络通信，支持多种协议和传输方式，是服务与外部世界交互的桥梁。
b.协议支持
a.gRPC协议
基于HTTP/2的高性能RPC框架，使用Protocol Buffers进行序列化，适合内部服务间通信。
b.HTTP协议
标准的RESTful API协议，支持JSON数据格式，适合Web应用和移动端接入。
c.自定义协议
支持用户自定义传输协议，满足特殊业务场景需求。
c.传输层特性
a.多路复用
支持在单个连接上处理多个并发请求，提高连接利用率。
b.流量控制
实现请求限流和背压控制，防止系统过载。
c.错误处理
统一的错误处理机制，支持错误传播和转换。
d.Transport使用示例
---
// Transport层使用示例
package transport
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/transport"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
)
// 创建HTTP传输层
func NewHTTPServer() transport.Server {
return http.NewServer(
http.Address(":8080"), // 监听地址
http.Timeout(time.Second*30), // 请求超时
http.Middleware( // 中间件
loggingMiddleware(),
recoveryMiddleware(),
authMiddleware(),
),
)
}
// 创建gRPC传输层
func NewGRPCServer() transport.Server {
return grpc.NewServer(
grpc.Address(":9090"), // 监听地址
grpc.Timeout(time.Second*30), // 请求超时
grpc.Middleware( // 中间件
loggingMiddleware(),
recoveryMiddleware(),
metricsMiddleware(),
),
grpc.UnaryInterceptor(unaryInterceptor()), // 一元拦截器
grpc.StreamInterceptor(streamInterceptor()), // 流式拦截器
)
}
// 请求拦截器
func unaryInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
start := time.Now()
resp, err := handler(ctx, req)
duration := time.Since(start)
// 记录请求日志
log.Infof("Method: %s, Duration: %v, Error: %v", info.FullMethod, duration, err)
return resp, err
}
}
// 流式拦截器
func streamInterceptor() grpc.StreamServerInterceptor {
return func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
log.Infof("Streaming method: %s", info.FullMethod)
return handler(srv, ss)
}
}
---
03.Service概念
a.服务定义
Service是业务逻辑的抽象，通过接口定义服务契约，实现业务功能的具体实现。
b.服务接口
a.接口设计
遵循面向接口的设计原则，通过Protocol Buffers定义服务接口和数据模型。
b.方法签名
支持一元调用、客户端流式、服务端流式和双向流式四种调用模式。
c.错误定义
使用标准化的错误码和错误消息，提供一致的错误处理体验。
c.服务实现
a.业务逻辑封装
将具体的业务逻辑封装在服务实现中，与传输层和基础设施层解耦。
b.依赖管理
通过依赖注入管理服务间的依赖关系，提高代码的可测试性和可维护性。
c.状态管理
处理业务状态的变化，包括数据一致性、事务管理等。
d.服务生命周期
a.初始化阶段
加载配置、建立连接、初始化状态等准备工作。
b.运行阶段
处理请求、调用其他服务、更新状态等业务操作。
c.清理阶段
释放资源、持久化状态、关闭连接等清理工作。
e.服务接口示例
---
// 用户服务接口定义
syntax = "proto3";
package user.v1;
import "google/protobuf/timestamp.proto";
import "google/api/annotations.proto";
// 用户服务
service UserService {
// 创建用户
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
body: "*"
};
}
// 获取用户信息
rpc GetUser(GetUserRequest) returns (GetUserResponse) {
option (google.api.http) = {
get: "/v1/users/{user_id}"
};
}
// 更新用户信息
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (google.api.http) = {
put: "/v1/users/{user_id}"
body: "*"
};
}
// 删除用户
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) {
option (google.api.http) = {
delete: "/v1/users/{user_id}"
};
}
// 列出用户（流式）
rpc ListUsers(ListUsersRequest) returns (stream ListUsersResponse) {
option (google.api.http) = {
get: "/v1/users"
};
}
// 批量操作（流式）
rpc BatchUserOperation(stream BatchUserOperationRequest) returns (BatchUserOperationResponse) {
option (google.api.http) = {
post: "/v1/users/batch"
body: "*"
};
}
}
// 用户信息消息
message User {
uint64 user_id = 1;
string username = 2;
string email = 3;
string full_name = 4;
google.protobuf.Timestamp created_at = 5;
google.protobuf.Timestamp updated_at = 6;
}
// 创建用户请求
message CreateUserRequest {
string username = 1;
string email = 2;
string full_name = 3;
string password = 4;
}
// 创建用户响应
message CreateUserResponse {
User user = 1;
}
// 获取用户请求
message GetUserRequest {
uint64 user_id = 1;
}
// 获取用户响应
message GetUserResponse {
User user = 1;
}
// 更新用户请求
message UpdateUserRequest {
uint64 user_id = 1;
string email = 2;
string full_name = 3;
}
// 更新用户响应
message UpdateUserResponse {
User user = 1;
}
// 删除用户请求
message DeleteUserRequest {
uint64 user_id = 1;
}
// 删除用户响应
message DeleteUserResponse {}
// 列出用户请求
message ListUsersRequest {
int32 page = 1;
int32 page_size = 2;
string filter = 3;
}
// 列出用户响应
message ListUsersResponse {
repeated User users = 1;
int64 total = 2;
}
// 批量操作请求
message BatchUserOperationRequest {
string operation = 1; // "create", "update", "delete"
User user = 2;
}
// 批量操作响应
message BatchUserOperationResponse {
int32 success_count = 1;
int32 failed_count = 2;
repeated string errors = 3;
}
---
04.Config概念
a.配置定义
Config组件提供统一的配置管理能力，支持多种数据源和动态更新机制。
b.配置源
a.文件配置
支持YAML、JSON、TOML等多种格式的配置文件。
b.环境变量
支持从系统环境变量中读取配置，便于容器化部署。
c.命令行参数
支持通过命令行参数覆盖配置文件中的值。
d.配置中心
集成Apollo、Nacos等配置中心，实现配置的集中管理。
c.配置特性
a.热更新
支持运行时动态更新配置，无需重启服务。
b.配置监听
提供配置变更事件通知机制，支持业务逻辑响应配置变化。
c.配置验证
支持配置项的类型检查和格式验证，确保配置的正确性。
d.配置示例
---
// 配置文件示例 (config.yaml)
server:
http:
addr: 0.0.0.0:8000
timeout: 1s
grpc:
addr: 0.0.0.0:9000
timeout: 1s
data:
database:
driver: mysql
source: user:password@tcp(127.0.0.1:3306)/dbname
redis:
addr: 127.0.0.1:6379
password: ""
db: 0
trace:
endpoint: http://localhost:14268/api/traces
auth:
jwt_secret: "your-secret-key"
token_expire: 24h
log:
level: info
format: json
// 配置结构体定义
package config
import (
"time"
"github.com/go-kratos/kratos/v2/config"
)
// 配置结构
type Config struct {
Server Server `json:"server"`
Data Data `json:"data"`
Trace Trace `json:"trace"`
Auth Auth `json:"auth"`
Log Log `json:"log"`
}
// 服务器配置
type Server struct {
HTTP HTTP `json:"http"`
GRPC GRPC `json:"grpc"`
}
type HTTP struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
}
type GRPC struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
}
// 数据配置
type Data struct {
Database Database `json:"database"`
Redis Redis `json:"redis"`
}
type Database struct {
Driver string `json:"driver"`
Source string `json:"source"`
}
type Redis struct {
Addr string `json:"addr"`
Password string `json:"password"`
DB int `json:"db"`
}
// 链路追踪配置
type Trace struct {
Endpoint string `json:"endpoint"`
}
// 认证配置
type Auth struct {
JWTSecret string `json:"jwt_secret"`
TokenExpire time.Duration `json:"token_expire"`
}
// 日志配置
type Log struct {
Level string `json:"level"`
Format string `json:"format"`
}
// 加载配置
func Load(path string) (*Config, error) {
c := config.New(
config.WithSource(
file.NewSource(path),
),
)
if err := c.Load(); err != nil {
return nil, err
}
var cfg Config
if err := c.Scan(&cfg); err != nil {
return nil, err
}
return &cfg, nil
}
---
05.Logging概念
a.日志定义
Logging组件提供结构化日志记录能力，支持多种输出格式和日志级别。
b.日志级别
a.DEBUG
调试信息，主要用于开发阶段的调试。
b.INFO
一般信息，记录应用正常运行的重要事件。
c.WARN
警告信息，表示可能出现问题但不影响正常运行。
d.ERROR
错误信息，记录应用运行中的错误和异常。
e.FATAL
致命错误，导致应用无法继续运行的严重错误。
c.日志特性
a.结构化日志
使用键值对格式记录日志，便于机器解析和查询分析。
b.上下文传递
支持在请求链路中传递上下文信息，实现日志的关联查询。
c.多输出目标
支持同时输出到文件、控制台、远程日志服务等多个目标。
d.日志使用示例
---
// 日志使用示例
package logging
import (
"context"
"os"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/logging"
)
// 创建日志记录器
func NewLogger() log.Logger {
return log.With(log.NewStdLogger(os.Stdout),
"ts", log.DefaultTimestamp,
"caller", log.DefaultCaller,
"service.name", "user-service",
"service.version", "v1.0.0",
)
}
// 日志中间件
func LoggingMiddleware() logging.ServerMiddleware {
return logging.Server(
logging.WithLogger(NewLogger()),
logging.WithLevel(log.LevelInfo),
logging.WithDuration(true),
logging.WithPayload(true),
)
}
// 业务日志记录
type UserService struct {
log log.Logger
}
func (s *UserService) CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error) {
// 记录请求开始
s.log.Log(log.LevelInfo, "create_user_start",
log.Context("trace_id", ctx.Value("trace_id")),
log.String("username", req.Username),
log.String("email", req.Email),
)
// 执行业务逻辑
user, err := s.createUser(ctx, req)
if err != nil {
// 记录错误日志
s.log.Log(log.LevelError, "create_user_failed",
log.Context("trace_id", ctx.Value("trace_id")),
log.String("username", req.Username),
log.String("error", err.Error()),
)
return nil, err
}
// 记录成功日志
s.log.Log(log.LevelInfo, "create_user_success",
log.Context("trace_id", ctx.Value("trace_id")),
log.Uint64("user_id", user.UserID),
log.String("username", user.Username),
)
return &CreateUserResponse{User: user}, nil
}
---
1.3 优缺点
01.Kratos优势
a.高性能特性
a.底层性能优势
基于Go语言的原生并发模型，采用轻量级协程(goroutine)实现高并发处理，单机可轻松支撑数万级别的并发连接。
b.网络通信优化
集成gRPC框架，基于HTTP/2协议实现多路复用，支持二进制数据传输和网络压缩，显著提升网络传输效率。
c.内存管理效率
Go语言的垃圾回收机制配合对象池模式，减少内存分配和回收开销，在高并发场景下保持稳定的内存使用。
d.性能测试示例
---
// 性能测试示例
package test
import (
"context"
"testing"
"time"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
pb "github.com/go-kratos/examples/helloworld/helloworld"
)
// 基准测试：HTTP性能
func BenchmarkHTTPServer(b *testing.B) {
server := http.NewServer(http.Address(":8080"))
pb.RegisterGreeterHTTPServer(server, &greeterService{})
go server.Start(context.Background())
defer server.Stop(context.Background())
client := http.NewClient(http.WithEndpoint("127.0.0.1:8080"))
conn := client.GetConnection()
b.ResetTimer()
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
resp, err := client.Call(context.Background(), "/helloworld.Greeter/SayHello", &pb.HelloRequest{Name: "benchmark"})
if err != nil {
b.Error(err)
}
_ = resp
}
})
}
// 基准测试：gRPC性能
func BenchmarkGRPCServer(b *testing.B) {
server := grpc.NewServer(grpc.Address(":9090"))
pb.RegisterGreeterServer(server, &greeterService{})
go server.Start(context.Background())
defer server.Stop(context.Background())
conn, err := grpc.Dial("127.0.0.1:9090", grpc.WithInsecure())
if err != nil {
b.Fatal(err)
}
defer conn.Close()
client := pb.NewGreeterClient(conn)
b.ResetTimer()
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
resp, err := client.SayHello(context.Background(), &pb.HelloRequest{Name: "benchmark"})
if err != nil {
b.Error(err)
}
_ = resp
}
})
}
// 性能统计
func BenchmarkMemoryAllocation(b *testing.B) {
var allocs testing.BenchmarkResult
b.ReportAllocs()
b.ResetTimer()
for i := 0; i < b.N; i++ {
resp, err := client.SayHello(context.Background(), &pb.HelloRequest{Name: "benchmark"})
if err != nil {
b.Error(err)
}
_ = resp
}
// 输出内存分配统计
b.Logf("Allocs per op: %d", allocs.AllocsPerOp())
b.Logf("Alloced bytes per op: %d", allocs.AllocedBytesPerOp())
}
---
b.云原生友好
a.容器化支持
提供官方Docker镜像和Kubernetes部署模板，支持健康检查、优雅关闭等容器化特性。
b.可观测性
内置Prometheus监控指标、结构化日志记录和OpenTelemetry链路追踪，符合云原生应用的可观测性要求。
c.配置管理
支持环境变量、配置文件和配置中心的动态配置加载，适应容器化环境的配置管理需求。
d.Kubernetes集成示例
---
# Kubernetes部署示例
apiVersion: apps/v1
kind: Deployment
metadata:
name: kratos-service
namespace: production
labels:
app: kratos-service
version: v1.0.0
spec:
replicas: 3
selector:
matchLabels:
app: kratos-service
template:
metadata:
labels:
app: kratos-service
version: v1.0.0
annotations:
prometheus.io/scrape: "true"
prometheus.io/port: "9000"
prometheus.io/path: "/metrics"
spec:
containers:
- name: kratos-service
image: kratos-service:v1.0.0
ports:
- name: http
containerPort: 8000
protocol: TCP
- name: grpc
containerPort: 9000
protocol: TCP
- name: metrics
containerPort: 9000
protocol: TCP
env:
- name: SERVER_HTTP_ADDR
value: "0.0.0.0:8000"
- name: SERVER_GRPC_ADDR
value: "0.0.0.0:9000"
- name: LOG_LEVEL
value: "info"
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 512Mi
livenessProbe:
httpGet:
path: /healthz
port: 8000
initialDelaySeconds: 30
periodSeconds: 10
readinessProbe:
httpGet:
path: /readyz
port: 8000
initialDelaySeconds: 5
periodSeconds: 5
lifecycle:
preStop:
exec:
command: ["/bin/sh", "-c", "sleep 15"]
---
c.开发者友好
a.代码生成工具
提供完整的代码生成工具链，根据Protocol Buffers定义自动生成服务接口、数据模型和API文档。
b.标准化项目结构
遵循Clean Architecture和DDD最佳实践，提供标准化的项目模板和目录结构。
c.丰富的中间件生态
内置认证、授权、限流、熔断等常用中间件，简化业务开发工作。
d.代码生成示例
---
// API定义文件 (api/user/v1/user.proto)
syntax = "proto3";
package user.v1;
import "google/api/annotations.proto";
service UserService {
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
body: "*"
};
}
}
// 代码生成命令
// go generate ./api
// 自动生成的服务接口
package user
import (
context "context"
)
type UserService interface {
CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error)
}
type CreateUserRequest struct {
Username string `json:"username"`
Email string `json:"email"`
}
type CreateUserResponse struct {
User *User `json:"user"`
}
---
d.生产级特性
a.错误处理机制
统一的错误处理框架，支持错误分类、错误传播和用户友好的错误消息。
b.服务治理能力
内置服务发现、负载均衡、熔断限流等服务治理功能，保障微服务系统的稳定性。
c.监控告警
集成Prometheus监控指标，支持自定义业务指标，提供完整的可观测性方案。
d.错误处理示例
---
// 错误处理示例
package errors
import (
"errors"
"fmt"
"github.com/go-kratos/kratos/v2/errors"
)
// 自定义错误类型
var (
ErrUserNotFound = errors.New("user not found")
ErrInvalidPassword = errors.New("invalid password")
ErrUnauthorized = errors.New("unauthorized")
)
// 业务错误处理
func (s *UserService) GetUser(ctx context.Context, req *GetUserRequest) (*GetUserResponse, error) {
user, err := s.userRepo.GetUser(ctx, req.UserId)
if err != nil {
if errors.Is(err, repository.ErrNotFound) {
return nil, errors.NotFound("USER_NOT_FOUND", "用户不存在")
}
return nil, errors.InternalServer("INTERNAL_ERROR", "内部服务器错误")
}
return &GetUserResponse{User: user}, nil
}
// 全局错误处理中间件
func ErrorHandlingMiddleware() middleware.Middleware {
return func(handler middleware.Handler) middleware.Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
resp, err := handler(ctx, req)
// 记录错误日志
if err != nil {
log.Error("request failed",
log.Context("trace_id", ctx.Value("trace_id")),
log.String("error", err.Error()),
)
// 转换为标准错误格式
if kratosErr, ok := err.(*errors.Error); ok {
return nil, kratosErr
}
return nil, errors.InternalServer("UNKNOWN_ERROR", "未知错误")
}
return resp, nil
}
}
}
---
02.Kratos局限性
a.学习曲线
a.概念复杂度
需要理解微服务架构、DDD、Clean Architecture等复杂概念，对新手开发者学习成本较高。
b.配置复杂度
框架提供了大量配置选项和自定义能力，需要开发者深入了解才能正确配置和使用。
c.调试难度
由于中间件、拦截器等抽象层的存在，问题定位和调试相对复杂。
d.学习资源示例
---
// 学习成本示例：完整的服务配置
package main
import (
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/tracing"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/prometheus/client_golang/prometheus"
)
func newApp(logger log.Logger, gs *grpc.Server, hs *http.Server) *kratos.App {
return kratos.New(
kratos.ID("demo"),
kratos.Name("demo"),
kratos.Version("v1.0.0"),
kratos.Metadata(map[string]string{}),
kratos.Logger(logger),
kratos.Server(
hs,
gs,
),
kratos.Registrar(),
kratos.BeforeStart(),
kratos.BeforeStop(),
kratos.AfterStart(),
kratos.AfterStop(),
)
}
func newGRPCServer(c *config.Config, greeter GreeterServer) *grpc.Server {
var opts = []grpc.ServerOption{
grpc.Middleware(
recovery.Recovery(),
tracing.Server(),
logging.Server(logger),
metrics.Server(),
),
}
if c != nil {
if httpAddr := c.GetString("server.grpc.addr"); httpAddr != "" {
opts = append(opts, grpc.Address(httpAddr))
}
if timeout := c.GetDuration("server.grpc.timeout"); timeout > 0 {
opts = append(opts, grpc.Timeout(timeout))
}
}
return grpc.NewServer(opts...)
}
func newHTTPServer(c *config.Config, greeter GreeterServer) *http.Server {
var opts = []http.ServerOption{
http.Middleware(
recovery.Recovery(),
tracing.Server(),
logging.Server(logger),
metrics.Server(),
),
}
if c != nil {
if httpAddr := c.GetString("server.http.addr"); httpAddr != "" {
opts = append(opts, http.Address(httpAddr))
}
if timeout := c.GetDuration("server.http.timeout"); timeout > 0 {
opts = append(opts, http.Timeout(timeout))
}
}
return http.NewServer(opts...)
}
---
b.社区生态
a.相对较小的社区
相比Spring Boot等成熟框架，Kratos的社区规模较小，第三方插件和工具相对较少。
b.文档资源有限
虽然官方文档比较完善，但社区分享的最佳实践、问题解决方案等资源相对有限。
c.人才储备不足
熟悉Kratos框架的开发者相对较少，企业招聘和团队建设存在一定挑战。
c.生态系统依赖
a.依赖Go生态
框架强依赖Go语言生态，在Java、Python等语言生态中无法使用。
b.微服务生态依赖
需要配合Kubernetes、Prometheus、Jaeger等云原生工具链，增加了部署复杂度。
c.运维要求高
微服务架构对运维团队的技术要求较高，需要熟悉分布式系统的监控、调试和故障处理。
d.运维复杂度示例
---
# 部署所需的基础设施组件
apiVersion: v1
kind: Namespace
metadata:
name: kratos-demo
---
# Prometheus监控配置
apiVersion: v1
kind: ConfigMap
metadata:
name: prometheus-config
namespace: kratos-demo
data:
prometheus.yml: |
global:
scrape_interval: 15s
scrape_configs:
- job_name: 'kratos-services'
consul_sd_configs:
- server: 'consul:8500'
relabel_configs:
- source_labels: [__meta_consul_tags]
regex: .*,metrics,.*
action: keep
---
# Jaeger链路追踪配置
apiVersion: v1
kind: ConfigMap
metadata:
name: jaeger-config
namespace: kratos-demo
data:
collector.yaml: |
sampling:
default_strategy:
type: probabilistic
param: 0.1
---
# 服务网格配置
apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
name: kratos-service
namespace: kratos-demo
spec:
http:
- match:
- uri:
prefix: "/api"
route:
- destination:
host: kratos-service
port:
number: 8080
timeout: 30s
retries:
attempts: 3
perTryTimeout: 10s
---
1.4 使用场景
01.企业级微服务应用
a.大型互联网应用
a.电商平台
支持商品管理、订单处理、支付系统、用户管理等核心业务模块的微服务化，实现高并发、高可用的电商系统。
b.社交网络
处理用户关系、消息推送、内容分发、实时通信等功能，支持数亿用户的社交互动需求。
c.金融科技
构建安全可靠的金融服务平台，包括账户管理、交易处理、风险控制、合规监管等核心功能。
d.电商微服务架构示例
---
// 电商微服务架构示例
package main
import (
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
)
// 商品服务
type ProductService struct {
productRepo ProductRepository
inventorySrv InventoryServiceClient
cacheSrv CacheService
}
// 商品服务接口定义
type ProductServiceServer interface {
CreateProduct(context.Context, *CreateProductRequest) (*CreateProductResponse, error)
GetProduct(context.Context, *GetProductRequest) (*GetProductResponse, error)
UpdateProduct(context.Context, *UpdateProductRequest) (*UpdateProductResponse, error)
DeleteProduct(context.Context, *DeleteProductRequest) (*DeleteProductResponse, error)
ListProducts(context.Context, *ListProductsRequest) (*ListProductsResponse, error)
SearchProducts(context.Context, *SearchProductsRequest) (*SearchProductsResponse, error)
}
// 订单服务
type OrderService struct {
orderRepo OrderRepository
userSrv UserServiceClient
productSrv ProductServiceClient
paymentSrv PaymentServiceClient
inventorySrv InventoryServiceClient
notificationSrv NotificationServiceClient
}
// 创建订单流程
func (s *OrderService) CreateOrder(ctx context.Context, req *CreateOrderRequest) (*CreateOrderResponse, error) {
// 1. 验证用户信息
user, err := s.userSrv.GetUser(ctx, &GetUserRequest{UserId: req.UserId})
if err != nil {
return nil, errors.New("用户不存在或已被禁用")
}
// 2. 验证商品信息并锁定库存
var orderItems []*OrderItem
for _, item := range req.Items {
product, err := s.productSrv.GetProduct(ctx, &GetProductRequest{ProductId: item.ProductId})
if err != nil {
return nil, fmt.Errorf("商品不存在: %d", item.ProductId)
}
// 锁定库存
lockResp, err := s.inventorySrv.LockInventory(ctx, &LockInventoryRequest{
ProductId: item.ProductId,
Quantity: item.Quantity,
OrderId: req.OrderId,
})
if err != nil {
return nil, fmt.Errorf("库存不足: %s", err.Error())
}
orderItems = append(orderItems, &OrderItem{
ProductId: item.ProductId,
ProductName: product.Name,
Price: product.Price,
Quantity: item.Quantity,
TotalPrice: product.Price * float64(item.Quantity),
})
}
// 3. 计算订单金额
totalAmount := 0.0
for _, item := range orderItems {
totalAmount += item.TotalPrice
}
// 4. 创建订单
order := &Order{
OrderId: req.OrderId,
UserId: req.UserId,
OrderItems: orderItems,
TotalAmount: totalAmount,
Status: OrderStatus_PENDING,
CreatedAt: time.Now(),
}
order, err = s.orderRepo.Create(ctx, order)
if err != nil {
// 回滚库存锁定
s.rollbackInventoryLock(ctx, req.OrderId, req.Items)
return nil, fmt.Errorf("创建订单失败: %s", err.Error())
}
// 5. 发送订单创建通知
s.notificationSrv.SendOrderCreatedNotification(ctx, &NotificationRequest{
UserId: req.UserId,
OrderId: req.OrderId,
Message: fmt.Sprintf("订单创建成功，订单金额：%.2f", totalAmount),
})
return &CreateOrderResponse{
Order: order,
}, nil
}
// 订单服务应用
func NewOrderServiceApp() *kratos.App {
return kratos.New(
kratos.Name("order-service"),
kratos.Version("v1.0.0"),
kratos.Server(
http.NewServer(
http.Address(":8080"),
),
grpc.NewServer(
grpc.Address(":9090"),
),
),
)
}
---
b.传统企业系统转型
a.单体应用拆分
将传统单体应用按业务边界拆分为多个微服务，实现系统的模块化和独立部署。
b.遗留系统集成
通过API网关和适配器模式，实现新微服务系统与遗留系统的平滑集成。
c.渐进式迁移
采用绞杀者模式，逐步替换原有系统组件，降低系统转型的风险。
d.银行系统微服务化示例
---
// 银行核心系统微服务化示例
package bank
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/log"
)
// 账户服务
type AccountService struct {
accountRepo AccountRepository
logger log.Logger
}
// 开户流程
func (s *AccountService) CreateAccount(ctx context.Context, req *CreateAccountRequest) (*CreateAccountResponse, error) {
// 1. 验证客户信息
customer, err := s.customerService.GetCustomer(ctx, req.CustomerId)
if err != nil {
return nil, errors.New("客户信息验证失败")
}
// 2. 风险评估
riskScore, err := s.riskService.AssessAccountRisk(ctx, &RiskAssessmentRequest{
CustomerId: req.CustomerId,
AccountType: req.AccountType,
InitialBalance: req.InitialBalance,
})
if err != nil || riskScore.Score > 80 {
return nil, errors.New("风险评估未通过，无法开户")
}
// 3. 生成账户号码
accountNumber := s.generateAccountNumber(req.AccountType)
// 4. 创建账户
account := &Account{
AccountNumber: accountNumber,
CustomerId: req.CustomerId,
AccountType: req.AccountType,
Balance: req.InitialBalance,
Status: AccountStatus_ACTIVE,
CreatedAt: time.Now(),
RiskScore: riskScore.Score,
}
account, err = s.accountRepo.Create(ctx, account)
if err != nil {
return nil, fmt.Errorf("账户创建失败: %s", err.Error())
}
// 5. 发送监管报告
s.regulatoryService.ReportAccountCreation(ctx, &RegulatoryReport{
AccountNumber: accountNumber,
CustomerId: req.CustomerId,
CreatedAt: time.Now(),
Operation: "CREATE_ACCOUNT",
})
s.logger.Infof("账户创建成功: %s, 客户: %d", accountNumber, req.CustomerId)
return &CreateAccountResponse{
Account: account,
}, nil
}
// 账户余额服务
type BalanceService struct {
accountRepo AccountRepository
transactionRepo TransactionRepository
auditService AuditService
}
// 余额变更
func (s *BalanceService) ChangeBalance(ctx context.Context, req *ChangeBalanceRequest) (*ChangeBalanceResponse, error) {
// 1. 验证账户状态
account, err := s.accountRepo.GetByNumber(ctx, req.AccountNumber)
if err != nil {
return nil, errors.New("账户不存在")
}
if account.Status != AccountStatus_ACTIVE {
return nil, errors.New("账户状态异常，无法进行余额操作")
}
// 2. 验证余额限制
newBalance := account.Balance + req.Amount
if newBalance < 0 {
return nil, errors.New("余额不足")
}
if req.Amount > 1000000 {
return nil, errors.New("单笔交易金额超出限制")
}
// 3. 创建交易记录
transaction := &Transaction{
TransactionId: s.generateTransactionId(),
AccountNumber: req.AccountNumber,
Amount: req.Amount,
TransactionType: req.TransactionType,
Description: req.Description,
Status: TransactionStatus_PENDING,
CreatedAt: time.Now(),
}
// 4. 执行余额变更（分布式事务）
err = s.executeBalanceChange(ctx, account, transaction)
if err != nil {
return nil, fmt.Errorf("余额变更失败: %s", err.Error())
}
// 5. 审计记录
s.auditService.RecordBalanceChange(ctx, &AuditRecord{
TransactionId: transaction.TransactionId,
AccountNumber: req.AccountNumber,
Amount: req.Amount,
OldBalance: account.Balance,
NewBalance: newBalance,
Operator: req.Operator,
Timestamp: time.Now(),
})
return &ChangeBalanceResponse{
TransactionId: transaction.TransactionId,
NewBalance: newBalance,
OldBalance: account.Balance,
}, nil
}
---
02.高并发场景应用
a.实时通信系统
a.聊天应用
支持即时消息、群组聊天、文件传输、语音视频通话等功能的微服务架构。
b.消息推送
构建大规模消息推送系统，支持千万级用户的实时消息推送和个性化推送。
c.直播平台
处理直播流媒体、实时弹幕、礼物打赏、观众互动等高并发场景。
d.实时通信示例
---
// 实时聊天服务示例
package chat
import (
"context"
"sync"
"time"
"github.com/go-kratos/kratos/v2/log"
"github.com/gorilla/websocket"
)
// 聊天服务
type ChatService struct {
connections map[string]*websocket.Conn
connectionLock sync.RWMutex
rooms map[string]*Room
roomLock sync.RWMutex
messageRepo MessageRepository
logger log.Logger
}
// 聊天房间
type Room struct {
RoomId string
Name string
Members map[string]*User
MaxMembers int
CreatedAt time.Time
mu sync.RWMutex
}
// 用户
type User struct {
UserId string
Username string
Avatar string
Conn *websocket.Conn
JoinedAt time.Time
LastSeen time.Time
}
// 消息
type Message struct {
MessageId string
RoomId string
UserId string
Username string
Content string
MessageType MessageType
CreatedAt time.Time
}
// 加入聊天室
func (s *ChatService) JoinRoom(ctx context.Context, req *JoinRoomRequest) (*JoinRoomResponse, error) {
s.connectionLock.Lock()
defer s.connectionLock.Unlock()
// 1. 验证房间存在性
room, exists := s.rooms[req.RoomId]
if !exists {
return nil, errors.New("房间不存在")
}
// 2. 检查房间容量
if len(room.Members) >= room.MaxMembers {
return nil, errors.New("房间已满")
}
// 3. 创建用户连接
user := &User{
UserId: req.UserId,
Username: req.Username,
Conn: req.Conn,
JoinedAt: time.Now(),
}
// 4. 加入房间
room.mu.Lock()
room.Members[req.UserId] = user
room.mu.Unlock()
s.connections[req.UserId] = req.Conn
// 5. 广播用户加入消息
joinMessage := &Message{
MessageId: s.generateMessageId(),
RoomId: req.RoomId,
UserId: req.UserId,
Username: req.Username,
Content: fmt.Sprintf("%s 加入了聊天室", req.Username),
MessageType: MessageType_SYSTEM,
CreatedAt: time.Now(),
}
s.broadcastToRoom(req.RoomId, joinMessage)
// 6. 记录用户加入
s.logger.Infof("用户 %s 加入房间 %s", req.Username, req.RoomId)
return &JoinRoomResponse{
Success: true,
Room: room,
}, nil
}
// 发送消息
func (s *ChatService) SendMessage(ctx context.Context, req *SendMessageRequest) (*SendMessageResponse, error) {
// 1. 验证用户连接
conn, exists := s.connections[req.UserId]
if !exists {
return nil, errors.New("用户连接不存在")
}
// 2. 验证房间
room, exists := s.rooms[req.RoomId]
if !exists {
return nil, errors.New("房间不存在")
}
// 3. 验证用户在房间中
room.mu.RLock()
_, inRoom := room.Members[req.UserId]
room.mu.RUnlock()
if !inRoom {
return nil, errors.New("用户不在房间中")
}
// 4. 内容过滤
if s.containsSensitiveWords(req.Content) {
return nil, errors.New("消息内容包含敏感词")
}
// 5. 创建消息
message := &Message{
MessageId: s.generateMessageId(),
RoomId: req.RoomId,
UserId: req.UserId,
Username: req.Username,
Content: req.Content,
MessageType: MessageType_TEXT,
CreatedAt: time.Now(),
}
// 6. 保存消息
err := s.messageRepo.Save(ctx, message)
if err != nil {
s.logger.Errorf("保存消息失败: %s", err.Error())
}
// 7. 广播消息
s.broadcastToRoom(req.RoomId, message)
return &SendMessageResponse{
MessageId: message.MessageId,
Timestamp: message.CreatedAt,
}, nil
}
// 广播消息到房间
func (s *ChatService) broadcastToRoom(roomId string, message *Message) {
room, exists := s.rooms[roomId]
if !exists {
return
}
room.mu.RLock()
defer room.mu.RUnlock()
for userId, user := range room.Members {
if err := user.Conn.WriteJSON(message); err != nil {
s.logger.Errorf("向用户 %s 发送消息失败: %s", userId, err.Error())
s.removeUser(userId)
}
}
}
// 移除用户
func (s *ChatService) removeUser(userId string) {
s.connectionLock.Lock()
defer s.connectionLock.Unlock()
if conn, exists := s.connections[userId]; exists {
conn.Close()
delete(s.connections, userId)
}
// 从所有房间中移除用户
for _, room := range s.rooms {
room.mu.Lock()
delete(room.Members, userId)
room.mu.Unlock()
leaveMessage := &Message{
MessageId: s.generateMessageId(),
RoomId: room.RoomId,
UserId: userId,
Username: "系统",
Content: fmt.Sprintf("用户 %s 离开了聊天室", userId),
MessageType: MessageType_SYSTEM,
CreatedAt: time.Now(),
}
s.broadcastToRoom(room.RoomId, leaveMessage)
}
}
---
b.物联网平台
a.设备管理
管理海量物联网设备的注册、认证、状态监控和远程控制。
b.数据采集
高效收集和处理来自大量设备的实时数据流，支持数据的清洗、转换和存储。
c.规则引擎
实现复杂的业务规则和自动化控制逻辑，支持设备联动和智能决策。
d.IoT设备管理示例
---
// IoT设备管理服务示例
package iot
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/log"
)
// 设备服务
type DeviceService struct {
deviceRepo DeviceRepository
telemetryRepo TelemetryRepository
ruleEngine RuleEngine
notification NotificationService
logger log.Logger
}
// 设备注册
func (s *DeviceService) RegisterDevice(ctx context.Context, req *RegisterDeviceRequest) (*RegisterDeviceResponse, error) {
// 1. 验证设备密钥
if !s.validateDeviceSecret(req.DeviceSecret) {
return nil, errors.New("设备密钥验证失败")
}
// 2. 生成设备ID和证书
deviceId := s.generateDeviceId()
deviceCert, err := s.generateDeviceCertificate(deviceId)
if err != nil {
return nil, fmt.Errorf("生成设备证书失败: %s", err.Error())
}
// 3. 创建设备记录
device := &Device{
DeviceId: deviceId,
DeviceName: req.DeviceName,
DeviceType: req.DeviceType,
Model: req.Model,
Firmware: req.Firmware,
Location: req.Location,
Status: DeviceStatus_OFFLINE,
LastSeen: time.Now(),
CreatedAt: time.Now(),
Certificate: deviceCert,
}
device, err = s.deviceRepo.Create(ctx, device)
if err != nil {
return nil, fmt.Errorf("设备注册失败: %s", err.Error())
}
// 4. 配置默认规则
s.configureDefaultRules(deviceId)
s.logger.Infof("设备注册成功: %s (%s)", deviceId, req.DeviceName)
return &RegisterDeviceResponse{
DeviceId: deviceId,
Certificate: deviceCert,
Endpoint: s.getDeviceEndpoint(deviceId),
}, nil
}
// 设备遥测数据处理
func (s *DeviceService) ProcessTelemetry(ctx context.Context, req *ProcessTelemetryRequest) (*ProcessTelemetryResponse, error) {
// 1. 验证设备
device, err := s.deviceRepo.GetByDeviceId(ctx, req.DeviceId)
if err != nil {
return nil, errors.New("设备不存在")
}
// 2. 更新设备状态
device.Status = DeviceStatus_ONLINE
device.LastSeen = time.Now()
s.deviceRepo.Update(ctx, device)
// 3. 解析遥测数据
telemetry, err := s.parseTelemetryData(req.RawData)
if err != nil {
return nil, fmt.Errorf("遥测数据解析失败: %s", err.Error())
}
// 4. 数据质量检查
if err := s.validateTelemetryData(telemetry); err != nil {
s.logger.Warnf("遥测数据质量检查失败: %s", err.Error())
return &ProcessTelemetryResponse{
Success: false,
Error: err.Error(),
}, nil
}
// 5. 保存遥测数据
for _, data := range telemetry {
data.DeviceId = req.DeviceId
data.Timestamp = time.Now()
err = s.telemetryRepo.Save(ctx, data)
if err != nil {
s.logger.Errorf("保存遥测数据失败: %s", err.Error())
}
}
// 6. 执行规则引擎
alerts, err := s.ruleEngine.EvaluateRules(ctx, device, telemetry)
if err != nil {
s.logger.Errorf("规则引擎执行失败: %s", err.Error())
} else {
// 发送告警通知
for _, alert := range alerts {
s.notification.SendAlert(ctx, &AlertRequest{
DeviceId: req.DeviceId,
AlertType: alert.Type,
AlertLevel: alert.Level,
Message: alert.Message,
Timestamp: time.Now(),
})
}
}
return &ProcessTelemetryResponse{
Success: true,
ProcessedCount: len(telemetry),
AlertsCount: len(alerts),
}, nil
}
// 设备命令执行
func (s *DeviceService) ExecuteCommand(ctx context.Context, req *ExecuteCommandRequest) (*ExecuteCommandResponse, error) {
// 1. 验证设备在线状态
device, err := s.deviceRepo.GetByDeviceId(ctx, req.DeviceId)
if err != nil {
return nil, errors.New("设备不存在")
}
if device.Status != DeviceStatus_ONLINE {
return nil, errors.New("设备离线，无法执行命令")
}
// 2. 验证命令权限
if !s.validateCommandPermission(req.UserId, req.CommandType) {
return nil, errors.New("没有执行该命令的权限")
}
// 3. 创建命令记录
command := &Command{
CommandId: s.generateCommandId(),
DeviceId: req.DeviceId,
UserId: req.UserId,
CommandType: req.CommandType,
Parameters: req.Parameters,
Status: CommandStatus_PENDING,
CreatedAt: time.Now(),
}
// 4. 发送命令到设备
err = s.sendCommandToDevice(device, command)
if err != nil {
command.Status = CommandStatus_FAILED
command.Error = err.Error()
s.deviceRepo.SaveCommand(ctx, command)
return nil, fmt.Errorf("命令发送失败: %s", err.Error())
}
command.Status = CommandStatus_SENT
s.deviceRepo.SaveCommand(ctx, command)
s.logger.Infof("命令发送成功: %s -> %s", command.CommandType, req.DeviceId)
return &ExecuteCommandResponse{
CommandId: command.CommandId,
Status: CommandStatus_SENT,
}, nil
}
---
03.数据处理与分析场景
a.大数据处理平台
a.数据采集服务
构建分布式数据采集系统，支持多种数据源的实时和批量数据收集。
b.数据清洗服务
实现数据标准化、去重、异常检测等数据清洗功能的微服务化。
c.数据分析服务
提供实时数据分析和批量数据处理能力，支持复杂的数据分析算法。
d.数据流处理示例
---
// 数据流处理服务示例
package dataprocessing
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/log"
)
// 数据处理服务
type DataProcessingService struct {
dataRepo DataRepository
processor DataProcessor
aggregator DataAggregator
exporter DataExporter
logger log.Logger
}
// 实时数据流处理
func (s *DataProcessingService) ProcessDataStream(ctx context.Context, req *ProcessDataStreamRequest) (*ProcessDataStreamResponse, error) {
// 1. 创建处理管道
pipeline := s.createProcessingPipeline(req.ProcessingConfig)
// 2. 处理数据流
var processedCount int64
var errorCount int64
var startTime = time.Now()
for _, record := range req.Records {
// 数据验证
if err := s.validateRecord(record); err != nil {
errorCount++
s.logger.Warnf("数据验证失败: %s", err.Error())
continue
}
// 数据转换
transformed, err := pipeline.Process(record)
if err != nil {
errorCount++
s.logger.Errorf("数据处理失败: %s", err.Error())
continue
}
// 保存处理结果
err = s.dataRepo.SaveProcessedData(ctx, transformed)
if err != nil {
errorCount++
s.logger.Errorf("保存处理结果失败: %s", err.Error())
continue
}
processedCount++
}
// 3. 生成处理报告
processingTime := time.Since(startTime)
throughput := float64(processedCount) / processingTime.Seconds()
return &ProcessDataStreamResponse{
ProcessedCount: processedCount,
ErrorCount: errorCount,
ProcessingTime: processingTime.String(),
Throughput: throughput,
}, nil
}
// 批量数据分析
func (s *DataProcessingService) AnalyzeDataBatch(ctx context.Context, req *AnalyzeDataBatchRequest) (*AnalyzeDataBatchResponse, error) {
// 1. 获取批量数据
dataBatch, err := s.dataRepo.GetDataBatch(ctx, req.BatchQuery)
if err != nil {
return nil, fmt.Errorf("获取批量数据失败: %s", err.Error())
}
// 2. 数据预处理
preprocessedData, err := s.processor.Preprocess(dataBatch)
if err != nil {
return nil, fmt.Errorf("数据预处理失败: %s", err.Error())
}
// 3. 执行分析算法
analysisResults := make([]*AnalysisResult, 0)
for _, algorithm := range req.Algorithms {
result, err := s.processor.Analyze(preprocessedData, algorithm)
if err != nil {
s.logger.Errorf("算法执行失败: %s", err.Error())
continue
}
analysisResults = append(analysisResults, result)
}
// 4. 数据聚合
aggregatedResults, err := s.aggregator.Aggregate(analysisResults)
if err != nil {
return nil, fmt.Errorf("数据聚合失败: %s", err.Error())
}
// 5. 导出分析结果
if req.ExportConfig != nil {
err = s.exporter.Export(ctx, aggregatedResults, req.ExportConfig)
if err != nil {
s.logger.Errorf("导出分析结果失败: %s", err.Error())
}
}
return &AnalyzeDataBatchResponse{
BatchId: req.BatchId,
DataCount: len(dataBatch),
AnalysisResults: aggregatedResults,
ProcessingTime: time.Since(time.Now()).String(),
}, nil
}
// 创建处理管道
func (s *DataProcessingService) createProcessingPipeline(config *ProcessingConfig) *Pipeline {
pipeline := NewPipeline()
// 添加数据验证器
pipeline.AddProcessor(&DataValidator{
RequiredFields: config.RequiredFields,
ValidationRules: config.ValidationRules,
})
// 添加数据转换器
for _, transform := range config.Transforms {
pipeline.AddProcessor(NewTransformer(transform))
}
// 添加数据过滤器
for _, filter := range config.Filters {
pipeline.AddProcessor(NewFilter(filter))
}
// 添加数据聚合器
if config.Aggregation != nil {
pipeline.AddProcessor(NewAggregator(config.Aggregation))
}
return pipeline
}
---
1.5 架构原理
01.分层架构设计
a.表示层(Presentation Layer)
a.协议适配
负责HTTP/gRPC协议的适配和转换，处理客户端请求的解析和响应的格式化。
b.数据序列化
使用Protocol Buffers进行数据序列化和反序列化，确保数据传输的高效性和兼容性。
c.接口路由
实现请求路由和方法分发，将客户端请求映射到具体的服务实现。
d.表示层架构示例
---
// 表示层架构示例
package presentation
import (
"context"
"net/http"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/gorilla/mux"
pb "github.com/your-project/api/user/v1"
)
// HTTP服务器实现
type HTTPServer struct {
router *mux.Router
userService pb.UserServiceServer
middleware []http.ServerOption
}
// 新建HTTP服务器
func NewHTTPServer(userService pb.UserServiceServer, opts ...http.ServerOption) *HTTPServer {
server := &HTTPServer{
router: mux.NewRouter(),
userService: userService,
middleware: opts,
}
server.setupRoutes()
return server
}
// 设置路由
func (s *HTTPServer) setupRoutes() {
// API版本分组
v1 := s.router.PathPrefix("/api/v1").Subrouter()
// 用户相关路由
v1.HandleFunc("/users", s.CreateUser).Methods("POST")
v1.HandleFunc("/users/{id}", s.GetUser).Methods("GET")
v1.HandleFunc("/users/{id}", s.UpdateUser).Methods("PUT")
v1.HandleFunc("/users/{id}", s.DeleteUser).Methods("DELETE")
v1.HandleFunc("/users", s.ListUsers).Methods("GET")
// 中间件应用
s.router.Use(s.authMiddleware)
s.router.Use(s.loggingMiddleware)
s.router.Use(s.recoveryMiddleware)
}
// 创建用户处理器
func (s *HTTPServer) CreateUser(w http.ResponseWriter, r *http.Request) {
var req pb.CreateUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "Invalid request body", http.StatusBadRequest)
return
}
// 转换为gRPC请求
resp, err := s.userService.CreateUser(r.Context(), &req)
if err != nil {
s.handleError(w, err)
return
}
s.writeJSON(w, resp, http.StatusCreated)
}
// 获取用户处理器
func (s *HTTPServer) GetUser(w http.ResponseWriter, r *http.Request) {
vars := mux.Vars(r)
userId := vars["id"]
req := &pb.GetUserRequest{
UserId: userId,
}
resp, err := s.userService.GetUser(r.Context(), req)
if err != nil {
s.handleError(w, err)
return
}
s.writeJSON(w, resp, http.StatusOK)
}
// 错误处理
func (s *HTTPServer) handleError(w http.ResponseWriter, err error) {
if errors.Is(err, ErrUserNotFound) {
http.Error(w, "User not found", http.StatusNotFound)
return
}
if errors.Is(err, ErrInvalidInput) {
http.Error(w, "Invalid input", http.StatusBadRequest)
return
}
http.Error(w, "Internal server error", http.StatusInternalServerError)
}
// JSON响应写入
func (s *HTTPServer) writeJSON(w http.ResponseWriter, data interface{}, statusCode int) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(statusCode)
json.NewEncoder(w).Encode(data)
}
// 认证中间件
func (s *HTTPServer) authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
token := r.Header.Get("Authorization")
if !s.validateToken(token) {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
// 日志中间件
func (s *HTTPServer) loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
// 创建响应写入器包装器
wrapper := &responseWrapper{ResponseWriter: w, statusCode: http.StatusOK}
next.ServeHTTP(wrapper, r)
duration := time.Since(start)
log.Printf("%s %s %d %v", r.Method, r.URL.Path, wrapper.statusCode, duration)
})
}
---
b.应用层(Application Layer)
a.应用服务
编排领域对象，执行具体的业务用例，协调领域服务完成业务功能。
b.事务管理
处理跨多个聚合根的事务操作，确保业务操作的一致性和完整性。
c.应用协调
负责领域对象之间的协调，以及与基础设施层的交互。
d.应用层架构示例
---
// 应用层架构示例
package application
import (
"context"
"errors"
"github.com/your-project/internal/domain"
"github.com/your-project/internal/infrastructure"
)
// 用户应用服务
type UserApplicationService struct {
userRepo domain.UserRepository
profileRepo domain.ProfileRepository
notificationSrv infrastructure.NotificationService
auditSrv infrastructure.AuditService
logger Logger
}
// 创建用户用例
func (s *UserApplicationService) CreateUser(ctx context.Context, cmd *CreateUserCommand) (*CreateUserResult, error) {
// 1. 验证用户数据
if err := s.validateUserData(cmd); err != nil {
return nil, err
}
// 2. 检查用户是否已存在
existingUser, err := s.userRepo.GetByEmail(ctx, cmd.Email)
if err == nil && existingUser != nil {
return nil, errors.New("用户已存在")
}
// 3. 创建用户聚合
user, err := domain.NewUser(
cmd.Username,
cmd.Email,
cmd.Password,
cmd.FullName,
)
if err != nil {
return nil, fmt.Errorf("创建用户失败: %s", err.Error())
}
// 4. 创建用户资料
profile, err := domain.NewUserProfile(
user.ID(),
cmd.Phone,
cmd.Address,
cmd.Avatar,
)
if err != nil {
return nil, fmt.Errorf("创建用户资料失败: %s", err.Error())
}
// 5. 执行业务规则验证
if err := s.userRepo.ValidateUser(ctx, user); err != nil {
return nil, fmt.Errorf("用户验证失败: %s", err.Error())
}
// 6. 保存用户和资料（事务操作）
err = s.userRepo.WithTransaction(ctx, func(txCtx context.Context) error {
// 保存用户
if err := s.userRepo.Save(txCtx, user); err != nil {
return fmt.Errorf("保存用户失败: %s", err.Error())
}
// 保存用户资料
if err := s.profileRepo.Save(txCtx, profile); err != nil {
return fmt.Errorf("保存用户资料失败: %s", err.Error())
}
return nil
})
if err != nil {
return nil, fmt.Errorf("创建用户事务失败: %s", err.Error())
}
// 7. 发送欢迎通知
err = s.notificationSrv.SendWelcomeEmail(ctx, &WelcomeEmailRequest{
UserId: user.ID(),
Username: user.Username(),
Email: user.Email(),
})
if err != nil {
s.logger.Errorf("发送欢迎邮件失败: %s", err.Error())
}
// 8. 记录审计日志
err = s.auditSrv.RecordAction(ctx, &AuditRecord{
UserId: user.ID(),
Action: "CREATE_USER",
Resource: "user",
ResourceId: user.ID(),
Timestamp: time.Now(),
Details: map[string]interface{}{
"username": user.Username(),
"email": user.Email(),
},
})
if err != nil {
s.logger.Errorf("记录审计日志失败: %s", err.Error())
}
return &CreateUserResult{
UserId: user.ID(),
Username: user.Username(),
Email: user.Email(),
Status: user.Status(),
}, nil
}
// 更新用户信息
func (s *UserApplicationService) UpdateUser(ctx context.Context, cmd *UpdateUserCommand) (*UpdateUserResult, error) {
// 1. 获取现有用户
user, err := s.userRepo.GetById(ctx, cmd.UserId)
if err != nil {
return nil, fmt.Errorf("用户不存在: %s", err.Error())
}
// 2. 检查权限
if !s.hasUpdatePermission(ctx, user.ID()) {
return nil, errors.New("无权限更新用户信息")
}
// 3. 验证更新数据
if err := s.validateUpdateData(cmd); err != nil {
return nil, err
}
// 4. 执行更新操作
oldUser := user.Clone() // 保存旧数据用于审计
if cmd.Email != "" && cmd.Email != user.Email() {
// 邮箱变更需要验证唯一性
if err := s.validateEmailUnique(ctx, cmd.Email, user.ID()); err != nil {
return nil, err
}
user.ChangeEmail(cmd.Email)
}
if cmd.FullName != "" {
user.ChangeFullName(cmd.FullName)
}
if cmd.Phone != "" {
user.ChangePhone(cmd.Phone)
}
if cmd.Avatar != "" {
user.ChangeAvatar(cmd.Avatar)
}
// 5. 保存更新
err = s.userRepo.Save(ctx, user)
if err != nil {
return nil, fmt.Errorf("更新用户失败: %s", err.Error())
}
// 6. 记录变更审计
err = s.auditSrv.RecordChange(ctx, &ChangeRecord{
UserId: user.ID(),
Action: "UPDATE_USER",
OldValue: oldUser,
NewValue: user,
Timestamp: time.Now(),
})
if err != nil {
s.logger.Errorf("记录变更审计失败: %s", err.Error())
}
return &UpdateUserResult{
UserId: user.ID(),
Username: user.Username(),
Email: user.Email(),
Status: user.Status(),
UpdatedAt: user.UpdatedAt(),
}, nil
}
// 验证用户数据
func (s *UserApplicationService) validateUserData(cmd *CreateUserCommand) error {
if cmd.Username == "" {
return errors.New("用户名不能为空")
}
if len(cmd.Username) < 3 || len(cmd.Username) > 20 {
return errors.New("用户名长度必须在3-20个字符之间")
}
if cmd.Email == "" {
return errors.New("邮箱不能为空")
}
if !s.isValidEmail(cmd.Email) {
return errors.New("邮箱格式不正确")
}
if cmd.Password == "" {
return errors.New("密码不能为空")
}
if len(cmd.Password) < 8 {
return errors.New("密码长度至少8个字符")
}
return nil
}
---
c.领域层(Domain Layer)
a.聚合根
定义业务的核心对象，封装业务规则和不变量，维护数据的一致性。
b.实体
具有唯一标识的业务对象，包含状态和行为，参与业务流程的执行。
c.值对象
描述业务属性的不可变对象，没有标识，通过属性值来定义相等性。
d.领域服务
封装不属于特定聚合根的业务逻辑，协调多个聚合根完成复杂业务操作。
e.领域层架构示例
---
// 领域层架构示例
package domain
import (
"errors"
"time"
"regexp"
)
// 用户聚合根
type User struct {
id UserId
username Username
email Email
password Password
fullName string
phone string
avatar string
status UserStatus
createdAt time.Time
updatedAt time.Time
version int
// 领域事件
events []DomainEvent
}
// 用户ID值对象
type UserId string
func (id UserId) String() string {
return string(id)
}
func (id UserId) IsEmpty() bool {
return string(id) == ""
}
// 用户名值对象
type Username string
func NewUsername(name string) (Username, error) {
if len(name) < 3 || len(name) > 20 {
return "", errors.New("用户名长度必须在3-20个字符之间")
}
if !regexp.MustCompile(`^[a-zA-Z0-9_]+$`).MatchString(name) {
return "", errors.New("用户名只能包含字母、数字和下划线")
}
return Username(name), nil
}
func (u Username) String() string {
return string(u)
}
// 邮箱值对象
type Email string
func NewEmail(email string) (Email, error) {
pattern := `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
matched, err := regexp.MatchString(pattern, email)
if err != nil || !matched {
return "", errors.New("邮箱格式不正确")
}
return Email(email), nil
}
func (e Email) String() string {
return string(e)
}
// 密码值对象
type Password struct {
hash string
salt string
}
func NewPassword(plainPassword string) (Password, error) {
if len(plainPassword) < 8 {
return Password{}, errors.New("密码长度至少8个字符")
}
salt := generateSalt()
hash := hashPassword(plainPassword, salt)
return Password{
hash: hash,
salt: salt,
}, nil
}
func (p Password) Verify(plainPassword string) bool {
return hashPassword(plainPassword, p.salt) == p.hash
}
// 用户状态值对象
type UserStatus string
const (
UserStatusActive UserStatus = "active"
UserStatusInactive UserStatus = "inactive"
UserStatusSuspended UserStatus = "suspended"
)
// 创建用户工厂方法
func NewUser(username Username, email Email, password Password, fullName string) (*User, error) {
if fullName == "" {
return nil, errors.New("全名不能为空")
}
user := &User{
id: UserId(generateId()),
username: username,
email: email,
password: password,
fullName: fullName,
status: UserStatusActive,
createdAt: time.Now(),
updatedAt: time.Now(),
version: 1,
}
// 添加领域事件
user.addEvent(&UserCreatedEvent{
UserId: user.id,
Username: user.username,
Email: user.email,
Timestamp: user.createdAt,
})
return user, nil
}
// 业务方法：修改邮箱
func (u *User) ChangeEmail(newEmail Email) error {
if newEmail == u.email {
return errors.New("新邮箱与当前邮箱相同")
}
oldEmail := u.email
u.email = newEmail
u.updatedAt = time.Now()
u.version++
// 添加领域事件
u.addEvent(&UserEmailChangedEvent{
UserId: u.id,
OldEmail: oldEmail,
NewEmail: newEmail,
Timestamp: u.updatedAt,
})
return nil
}
// 业务方法：修改全名
func (u *User) ChangeFullName(newFullName string) error {
if newFullName == "" {
return errors.New("全名不能为空")
}
if newFullName == u.fullName {
return nil
}
u.fullName = newFullName
u.updatedAt = time.Now()
u.version++
return nil
}
// 业务方法：修改手机号
func (u *User) ChangePhone(newPhone string) error {
// 验证手机号格式
if newPhone != "" && !regexp.MustCompile(`^1[3-9]\d{9}$`).MatchString(newPhone) {
return errors.New("手机号格式不正确")
}
u.phone = newPhone
u.updatedAt = time.Now()
u.version++
return nil
}
// 业务方法：修改头像
func (u *User) ChangeAvatar(newAvatar string) error {
if newAvatar == "" {
return errors.New("头像URL不能为空")
}
u.avatar = newAvatar
u.updatedAt = time.Now()
u.version++
return nil
}
// 业务方法：激活用户
func (u *User) Activate() error {
if u.status == UserStatusActive {
return errors.New("用户已经是激活状态")
}
u.status = UserStatusActive
u.updatedAt = time.Now()
u.version++
u.addEvent(&UserActivatedEvent{
UserId: u.id,
Timestamp: u.updatedAt,
})
return nil
}
// 业务方法：暂停用户
func (u *User) Suspend(reason string) error {
if u.status == UserStatusSuspended {
return errors.New("用户已经是暂停状态")
}
u.status = UserStatusSuspended
u.updatedAt = time.Now()
u.version++
u.addEvent(&UserSuspendedEvent{
UserId: u.id,
Reason: reason,
Timestamp: u.updatedAt,
})
return nil
}
// 领域事件处理
func (u *User) addEvent(event DomainEvent) {
u.events = append(u.events, event)
}
func (u *User) GetEvents() []DomainEvent {
return u.events
}
func (u *User) ClearEvents() {
u.events = []DomainEvent{}
}
// Getter方法
func (u *User) ID() UserId {
return u.id
}
func (u *User) Username() Username {
return u.username
}
func (u *User) Email() Email {
return u.email
}
func (u *User) FullName() string {
return u.fullName
}
func (u *User) Phone() string {
return u.phone
}
func (u *User) Avatar() string {
return u.avatar
}
func (u *User) Status() UserStatus {
return u.status
}
func (u *User) CreatedAt() time.Time {
return u.createdAt
}
func (u *User) UpdatedAt() time.Time {
return u.updatedAt
}
func (u *User) Version() int {
return u.version
}
// 克隆方法
func (u *User) Clone() *User {
clone := *u
clone.events = make([]DomainEvent, len(u.events))
copy(clone.events, u.events)
return &clone
}
// 领域事件接口
type DomainEvent interface {
EventId() string
Timestamp() time.Time
}
// 用户创建事件
type UserCreatedEvent struct {
UserId UserId
Username Username
Email Email
}
func (e *UserCreatedEvent) EventId() string {
return generateEventId()
}
func (e *UserCreatedEvent) Timestamp() time.Time {
return time.Now()
}
// 邮箱变更事件
type UserEmailChangedEvent struct {
UserId UserId
OldEmail Email
NewEmail Email
}
func (e *UserEmailChangedEvent) EventId() string {
return generateEventId()
}
func (e *UserEmailChangedEvent) Timestamp() time.Time {
return time.Now()
}
---
d.基础设施层(Infrastructure Layer)
a.数据持久化
实现领域对象的数据访问和持久化，提供Repository模式的具体实现。
b.外部服务集成
封装与外部系统的交互，如消息队列、缓存服务、第三方API等。
c.技术支持
提供日志记录、配置管理、监控告警等技术基础设施支持。
d.基础设施层架构示例
---
// 基础设施层架构示例
package infrastructure
import (
"context"
"database/sql"
"time"
"github.com/your-project/internal/domain"
"github.com/go-redis/redis/v8"
)
// 用户仓储实现
type UserRepositoryImpl struct {
db *sql.DB
cache *redis.Client
logger Logger
}
// 新建用户仓储
func NewUserRepository(db *sql.DB, cache *redis.Client, logger Logger) domain.UserRepository {
return &UserRepositoryImpl{
db: db,
cache: cache,
logger: logger,
}
}
// 保存用户
func (r *UserRepositoryImpl) Save(ctx context.Context, user *domain.User) error {
query := `
INSERT INTO users (
id, username, email, password_hash, password_salt,
full_name, phone, avatar, status, created_at, updated_at, version
) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT (id) DO UPDATE SET
username = ?, email = ?, password_hash = ?, password_salt = ?,
full_name = ?, phone = ?, avatar = ?, status = ?,
updated_at = ?, version = ?
`
tx, err := r.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("开始事务失败: %s", err.Error())
}
defer tx.Rollback()
_, err = tx.ExecContext(ctx, query,
user.ID().String(), user.Username().String(), user.Email().String(),
user.password.hash, user.password.salt, user.FullName(), user.Phone(),
user.Avatar(), string(user.Status()), user.CreatedAt(), user.UpdatedAt(), user.Version(),
user.Username().String(), user.Email().String(), user.password.hash, user.password.salt,
user.FullName(), user.Phone(), user.Avatar(), string(user.Status()),
user.UpdatedAt(), user.Version(),
)
if err != nil {
return fmt.Errorf("保存用户失败: %s", err.Error())
}
// 保存领域事件
if err := r.saveDomainEvents(ctx, tx, user); err != nil {
return fmt.Errorf("保存领域事件失败: %s", err.Error())
}
// 提交事务
if err := tx.Commit(); err != nil {
return fmt.Errorf("提交事务失败: %s", err.Error())
}
// 清除缓存
r.clearUserCache(user.ID())
r.logger.Infof("用户保存成功: %s", user.ID().String())
return nil
}
// 根据ID获取用户
func (r *UserRepositoryImpl) GetById(ctx context.Context, id domain.UserId) (*domain.User, error) {
// 先从缓存获取
user, err := r.getUserFromCache(ctx, id)
if err == nil {
return user, nil
}
query := `
SELECT id, username, email, password_hash, password_salt,
full_name, phone, avatar, status, created_at, updated_at, version
FROM users
WHERE id = ? AND deleted_at IS NULL
`
var userEntity UserEntity
err = r.db.QueryRowContext(ctx, query, id.String()).Scan(
&userEntity.Id, &userEntity.Username, &userEntity.Email,
&userEntity.PasswordHash, &userEntity.PasswordSalt,
&userEntity.FullName, &userEntity.Phone, &userEntity.Avatar,
&userEntity.Status, &userEntity.CreatedAt, &userEntity.UpdatedAt, &userEntity.Version,
)
if err != nil {
if err == sql.ErrNoRows {
return nil, domain.ErrUserNotFound
}
return nil, fmt.Errorf("查询用户失败: %s", err.Error())
}
// 转换为领域对象
user, err = r.entityToUser(&userEntity)
if err != nil {
return nil, fmt.Errorf("实体转换失败: %s", err.Error())
}
// 缓存用户数据
r.cacheUser(ctx, user)
return user, nil
}
// 根据邮箱获取用户
func (r *UserRepositoryImpl) GetByEmail(ctx context.Context, email domain.Email) (*domain.User, error) {
query := `
SELECT id, username, email, password_hash, password_salt,
full_name, phone, avatar, status, created_at, updated_at, version
FROM users
WHERE email = ? AND deleted_at IS NULL
`
var userEntity UserEntity
err := r.db.QueryRowContext(ctx, query, email.String()).Scan(
&userEntity.Id, &userEntity.Username, &userEntity.Email,
&userEntity.PasswordHash, &userEntity.PasswordSalt,
&userEntity.FullName, &userEntity.Phone, &userEntity.Avatar,
&userEntity.Status, &userEntity.CreatedAt, &userEntity.UpdatedAt, &userEntity.Version,
)
if err != nil {
if err == sql.ErrNoRows {
return nil, domain.ErrUserNotFound
}
return nil, fmt.Errorf("查询用户失败: %s", err.Error())
}
return r.entityToUser(&userEntity)
}
// 验证用户
func (r *UserRepositoryImpl) ValidateUser(ctx context.Context, user *domain.User) error {
// 检查用户名是否已存在
var count int
err := r.db.QueryRowContext(ctx,
"SELECT COUNT(*) FROM users WHERE username = ? AND id != ? AND deleted_at IS NULL",
user.Username().String(), user.ID().String()).Scan(&count)
if err != nil {
return fmt.Errorf("检查用户名唯一性失败: %s", err.Error())
}
if count > 0 {
return domain.ErrUsernameExists
}
return nil
}
// 事务执行
func (r *UserRepositoryImpl) WithTransaction(ctx context.Context, fn func(context.Context) error) error {
tx, err := r.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("开始事务失败: %s", err.Error())
}
defer tx.Rollback()
// 将事务上下文传递给回调函数
txCtx := context.WithValue(ctx, "tx", tx)
if err := fn(txCtx); err != nil {
return err
}
return tx.Commit()
}
// 实体到领域对象转换
func (r *UserRepositoryImpl) entityToUser(entity *UserEntity) (*domain.User, error) {
username, err := domain.NewUsername(entity.Username)
if err != nil {
return nil, fmt.Errorf("无效的用户名: %s", err.Error())
}
email, err := domain.NewEmail(entity.Email)
if err != nil {
return nil, fmt.Errorf("无效的邮箱: %s", err.Error())
}
password := domain.Password{
hash: entity.PasswordHash,
salt: entity.PasswordSalt,
}
user := &domain.User{
id: domain.UserId(entity.Id),
username: username,
email: email,
password: password,
fullName: entity.FullName,
phone: entity.Phone,
avatar: entity.Avatar,
status: domain.UserStatus(entity.Status),
createdAt: entity.CreatedAt,
updatedAt: entity.UpdatedAt,
version: entity.Version,
}
return user, nil
}
// 缓存用户
func (r *UserRepositoryImpl) cacheUser(ctx context.Context, user *domain.User) {
key := fmt.Sprintf("user:%s", user.ID().String())
userJSON, _ := json.Marshal(user)
r.cache.Set(ctx, key, userJSON, 5*time.Minute)
}
// 从缓存获取用户
func (r *UserRepositoryImpl) getUserFromCache(ctx context.Context, id domain.UserId) (*domain.User, error) {
key := fmt.Sprintf("user:%s", id.String())
userJSON, err := r.cache.Get(ctx, key).Result()
if err != nil {
return nil, err
}
var user domain.User
err = json.Unmarshal([]byte(userJSON), &user)
if err != nil {
return nil, err
}
return &user, nil
}
// 清除用户缓存
func (r *UserRepositoryImpl) clearUserCache(id domain.UserId) {
key := fmt.Sprintf("user:%s", id.String())
r.cache.Del(context.Background(), key)
}
// 保存领域事件
func (r *UserRepositoryImpl) saveDomainEvents(ctx context.Context, tx *sql.Tx, user *domain.User) error {
events := user.GetEvents()
if len(events) == 0 {
return nil
}
for _, event := range events {
eventJSON, err := json.Marshal(event)
if err != nil {
return fmt.Errorf("序列化领域事件失败: %s", err.Error())
}
query := `
INSERT INTO domain_events (
id, aggregate_id, aggregate_type, event_type,
event_data, timestamp, version
) VALUES (?, ?, ?, ?, ?, ?, ?)
`
_, err = tx.ExecContext(ctx, query,
event.EventId(), user.ID().String(), "user", event.Timestamp().String(),
string(eventJSON), event.Timestamp(), user.Version(),
)
if err != nil {
return fmt.Errorf("保存领域事件失败: %s", err.Error())
}
}
// 清空已保存的事件
user.ClearEvents()
return nil
}
// 用户数据库实体
type UserEntity struct {
Id string
Username string
Email string
PasswordHash string
PasswordSalt string
FullName string
Phone string
Avatar string
Status string
CreatedAt time.Time
UpdatedAt time.Time
Version int
}
---
1.6 设计理念
01.领域驱动设计(DDD)
a.战略设计
a.领域划分
通过限界上下文(Bounded Context)划分业务领域，明确各子系统的职责边界和交互关系。
b.聚合设计
识别核心聚合根，确保聚合内部的一致性边界，避免跨聚合的强一致性要求。
c.上下文映射
定义不同限界上下文之间的关系，包括共享内核、客户/供应商、防腐层等模式。
d.DDD战略设计示例
---
// 电商系统领域划分示例
package ddd
// 限界上下文定义
type BoundedContext interface {
Name() string
Type() ContextType
Entities() []string
Aggregates() []string
}
// 上下文类型
type ContextType int
const (
ContextTypeCore ContextType = iota
ContextTypeSupporting
ContextTypeGeneric
ContextTypeIntegration
)
// 用户上下文
type UserContext struct{}
func (uc *UserContext) Name() string { return "User Context" }
func (uc *UserContext) Type() ContextType { return ContextTypeCore }
func (uc *UserContext) Entities() []string {
return []string{"User", "UserProfile", "UserPreference"}
}
func (uc *UserContext) Aggregates() []string {
return []string{"User"}
}
// 商品上下文
type ProductContext struct{}
func (pc *ProductContext) Name() string { return "Product Context" }
func (pc *ProductContext) Type() ContextType { return ContextTypeCore }
func (pc *ProductContext) Entities() []string {
return []string{"Product", "Category", "ProductVariant"}
}
func (pc *ProductContext) Aggregates() []string {
return []string{"Product", "Category"}
}
// 订单上下文
type OrderContext struct{}
func (oc *OrderContext) Name() string { return "Order Context" }
func (oc *OrderContext) Type() ContextType { return ContextTypeCore }
func (oc *OrderContext) Entities() []string {
return []string{"Order", "OrderItem", "Payment", "Shipment"}
}
func (oc *OrderContext) Aggregates() []string {
return []string{"Order", "Payment"}
}
// 库存上下文
type InventoryContext struct{}
func (ic *InventoryContext) Name() string { return "Inventory Context" }
func (ic *InventoryContext) Type() ContextType { return ContextTypeSupporting }
func (ic *InventoryContext) Entities() []string {
return []string{"Inventory", "StockMovement", "Reservation"}
}
func (ic *InventoryContext) Aggregates() []string {
return []string{"Inventory"}
}
// 上下文映射关系
type ContextMapping struct {
Source BoundedContext
Target BoundedContext
Relation RelationType
Description string
}
type RelationType int
const (
RelationTypeSharedKernel RelationType = iota
RelationTypeCustomerSupplier
RelationTypeConformist
RelationTypeAntiCorruption
RelationTypeOpenHost
RelationTypePublishedLanguage
)
// 建立上下文映射
func CreateContextMappings() []*ContextMapping {
return []*ContextMapping{
{
Source: &UserContext{},
Target: &OrderContext{},
Relation: RelationTypeCustomerSupplier,
Description: "订单上下文需要用户信息，用户上下文提供用户服务",
},
{
Source: &ProductContext{},
Target: &OrderContext{},
Relation: RelationTypeCustomerSupplier,
Description: "订单上下文需要商品信息，商品上下文提供商品服务",
},
{
Source: &InventoryContext{},
Target: &OrderContext{},
Relation: RelationTypeCustomerSupplier,
Description: "订单上下文需要库存信息，库存上下文提供库存服务",
},
{
Source: &OrderContext{},
Target: &InventoryContext{},
Relation: RelationTypeCustomerSupplier,
Description: "库存上下文需要订单信息来处理库存预留",
},
}
}
// 聚合根设计
type AggregateRoot interface {
ID() string
Version() int
Events() []DomainEvent
ClearEvents()
}
// 用户聚合根
type UserAggregate struct {
id UserId
username Username
email Email
profile UserProfile
status UserStatus
version int
events []DomainEvent
}
func (ua *UserAggregate) ID() string { return ua.id.String() }
func (ua *UserAggregate) Version() int { return ua.version }
func (ua *UserAggregate) Events() []DomainEvent { return ua.events }
func (ua *UserAggregate) ClearEvents() { ua.events = []DomainEvent{} }
// 业务不变量
func (ua *UserAggregate) ChangeEmail(newEmail Email) error {
if ua.email == newEmail {
return nil
}
// 不变量：每个用户的邮箱必须唯一
if !ua.isEmailUnique(newEmail) {
return errors.New("邮箱已被使用")
}
ua.email = newEmail
ua.version++
ua.addEvent(&UserEmailChangedEvent{
UserId: ua.id,
OldEmail: ua.email,
NewEmail: newEmail,
Timestamp: time.Now(),
})
return nil
}
func (ua *UserAggregate) isEmailUnique(email Email) bool {
// 调用领域服务验证邮箱唯一性
return UserService.IsEmailUnique(ua.id, email)
}
---
b.战术设计
a.实体与值对象
区分具有唯一标识的实体和通过属性值定义的值对象，正确建模业务概念。
b.聚合设计
确定聚合根，定义聚合内部的一致性规则，通过聚合根控制对聚合内部的访问。
c.领域服务
为不属于特定实体的业务逻辑创建领域服务，保持模型的表达能力。
d.仓储模式
使用Repository模式抽象数据访问，将领域逻辑与基础设施实现解耦。
e.领域事件
通过领域事件解耦聚合之间的协作，实现最终一致性。
f.聚合设计示例
---
// 订单聚合设计示例
package order
import (
"errors"
"time"
"math"
)
// 订单聚合根
type Order struct {
id OrderId
customerId CustomerId
items []OrderItem
status OrderStatus
totalPrice Money
address ShippingAddress
paymentInfo PaymentInfo
createdAt time.Time
updatedAt time.Time
version int
events []DomainEvent
}
// 订单项实体
type OrderItem struct {
productId ProductId
productName string
quantity int
unitPrice Money
totalPrice Money
}
// 金钱值对象
type Money struct {
amount int64
currency Currency
}
func (m Money) Amount() int64 { return m.amount }
func (m Money) Currency() Currency { return m.currency }
func NewMoney(amount int64, currency Currency) (Money, error) {
if amount < 0 {
return Money{}, errors.New("金额不能为负数")
}
return Money{amount: amount, currency: currency}, nil
}
func (m Money) Add(other Money) (Money, error) {
if m.currency != other.currency {
return Money{}, errors.New("货币类型不同，不能相加")
}
return Money{
amount: m.amount + other.amount,
currency: m.currency,
}, nil
}
// 配送地址值对象
type ShippingAddress struct {
street string
city string
province string
country string
zipCode string
}
func NewShippingAddress(street, city, province, country, zipCode string) (ShippingAddress, error) {
if street == "" || city == "" || country == "" || zipCode == "" {
return ShippingAddress{}, errors.New("地址信息不完整")
}
return ShippingAddress{
street: street,
city: city,
province: province,
country: country,
zipCode: zipCode,
}, nil
}
// 订单状态值对象
type OrderStatus string
const (
OrderStatusPending OrderStatus = "pending"
OrderStatusConfirmed OrderStatus = "confirmed"
OrderStatusPaid OrderStatus = "paid"
OrderStatusShipped OrderStatus = "shipped"
OrderStatusDelivered OrderStatus = "delivered"
OrderStatusCancelled OrderStatus = "cancelled"
OrderStatusRefunded OrderStatus = "refunded"
)
// 创建订单工厂方法
func NewOrder(customerId CustomerId, items []OrderItem, address ShippingAddress) (*Order, error) {
if len(items) == 0 {
return nil, errors.New("订单项不能为空")
}
// 验证每个订单项
for _, item := range items {
if item.quantity <= 0 {
return nil, errors.New("商品数量必须大于0")
}
if item.unitPrice.amount <= 0 {
return nil, errors.New("商品单价必须大于0")
}
}
// 计算总价
var totalPrice Money
for _, item := range items {
totalPrice, _ = totalPrice.Add(item.totalPrice)
}
// 检查最大订单金额限制
if totalPrice.amount > 10000000 { // 10万元限制
return nil, errors.New("订单金额超出最大限制")
}
order := &Order{
id: generateOrderId(),
customerId: customerId,
items: items,
status: OrderStatusPending,
totalPrice: totalPrice,
address: address,
createdAt: time.Now(),
updatedAt: time.Now(),
version: 1,
}
// 发布订单创建事件
order.addEvent(&OrderCreatedEvent{
OrderId: order.id,
CustomerId: order.customerId,
TotalPrice: order.totalPrice,
Timestamp: order.createdAt,
})
return order, nil
}
// 添加订单项
func (o *Order) AddItem(item OrderItem) error {
if o.status != OrderStatusPending {
return errors.New("只能在待确认状态下添加商品")
}
// 检查商品是否已存在
for i, existingItem := range o.items {
if existingItem.productId == item.productId {
// 更新数量和价格
newQuantity := existingItem.quantity + item.quantity
if newQuantity > 100 { // 单个商品最大数量限制
return errors.New("单个商品数量超出限制")
}
o.items[i].quantity = newQuantity
o.items[i].totalPrice = Money{
amount: int64(newQuantity) * existingItem.unitPrice.amount,
currency: existingItem.unitPrice.currency,
}
o.recalculateTotalPrice()
o.version++
o.updatedAt = time.Now()
o.addEvent(&OrderItemUpdatedEvent{
OrderId: o.id,
ProductId: item.productId,
NewQuantity: newQuantity,
Timestamp: o.updatedAt,
})
return nil
}
}
// 新增商品
if len(o.items) >= 50 { // 订单项数量限制
return errors.New("订单项数量超出限制")
}
o.items = append(o.items, item)
o.recalculateTotalPrice()
o.version++
o.updatedAt = time.Now()
o.addEvent(&OrderItemAddedEvent{
OrderId: o.id,
ProductId: item.productId,
Quantity: item.quantity,
Timestamp: o.updatedAt,
})
return nil
}
// 确认订单
func (o *Order) Confirm() error {
if o.status != OrderStatusPending {
return errors.New("只能在待确认状态下确认订单")
}
if len(o.items) == 0 {
return errors.New("订单项不能为空")
}
o.status = OrderStatusConfirmed
o.version++
o.updatedAt = time.Now()
o.addEvent(&OrderConfirmedEvent{
OrderId: o.id,
Timestamp: o.updatedAt,
})
return nil
}
// 支付订单
func (o *Order) Pay(paymentInfo PaymentInfo) error {
if o.status != OrderStatusConfirmed {
return errors.New("只能在已确认状态下支付订单")
}
// 验证支付金额
if paymentInfo.amount.amount != o.totalPrice.amount {
return errors.New("支付金额与订单金额不匹配")
}
o.paymentInfo = paymentInfo
o.status = OrderStatusPaid
o.version++
o.updatedAt = time.Now()
o.addEvent(&OrderPaidEvent{
OrderId: o.id,
PaymentId: paymentInfo.paymentId,
Amount: paymentInfo.amount,
Timestamp: o.updatedAt,
})
return nil
}
// 取消订单
func (o *Order) Cancel(reason string) error {
if o.status == OrderStatusDelivered || o.status == OrderStatusRefunded {
return errors.New("已送达或已退款订单无法取消")
}
oldStatus := o.status
o.status = OrderStatusCancelled
o.version++
o.updatedAt = time.Now()
o.addEvent(&OrderCancelledEvent{
OrderId: o.id,
OldStatus: oldStatus,
Reason: reason,
Timestamp: o.updatedAt,
})
return nil
}
// 重新计算总价
func (o *Order) recalculateTotalPrice() {
var total Money
for _, item := range o.items {
total, _ = total.Add(item.totalPrice)
}
o.totalPrice = total
}
// 领域事件处理
func (o *Order) addEvent(event DomainEvent) {
o.events = append(o.events, event)
}
func (o *Order) GetEvents() []DomainEvent {
return o.events
}
func (o *Order) ClearEvents() {
o.events = []DomainEvent{}
}
// Getter方法
func (o *Order) ID() OrderId { return o.id }
func (o *Order) CustomerId() CustomerId { return o.customerId }
func (o *Order) Items() []OrderItem { return o.items }
func (o *Order) Status() OrderStatus { return o.status }
func (o *Order) TotalPrice() Money { return o.totalPrice }
func (o *Order) CreatedAt() time.Time { return o.createdAt }
func (o *Order) Version() int { return o.version }
---
02.Clean Architecture
a.依赖倒置原则
高层模块不依赖低层模块，两者都依赖抽象；抽象不依赖细节，细节依赖抽象。
b.关注点分离
将业务逻辑与基础设施关注点分离，确保业务代码的纯粹性和可测试性。
c.可测试性
通过依赖注入和接口抽象，使业务逻辑能够独立于外部依赖进行测试。
d.依赖方向
表示层 → 应用层 → 领域层 ← 基础设施层
e.Clean Architecture示例
---
// Clean Architecture层次结构示例
package architecture
// 1. 领域层 - 最内层，不依赖任何外部库
package domain
// 用户领域服务
type UserDomainService interface {
IsUsernameUnique(userId UserId, username Username) bool
IsEmailUnique(userId UserId, email Email) bool
ValidateUserPassword(userId UserId, password Password) bool
}
// 用户仓储接口
type UserRepository interface {
Save(ctx context.Context, user *User) error
GetById(ctx context.Context, id UserId) (*User, error)
GetByEmail(ctx context.Context, email Email) (*User, error)
Delete(ctx context.Context, id UserId) error
}
// 用户聚合根
type User struct {
// 领域逻辑实现...
}
// 2. 应用层 - 依赖领域层接口
package application
import "github.com/your-project/internal/domain"
// 用户应用服务
type UserApplicationService struct {
userRepo domain.UserRepository
userDomainSrv domain.UserDomainService
notificationSrv NotificationService // 外部服务接口
logger Logger // 外部服务接口
}
// 依赖注入构造函数
func NewUserApplicationService(
userRepo domain.UserRepository,
userDomainSrv domain.UserDomainService,
notificationSrv NotificationService,
logger Logger,
) *UserApplicationService {
return &UserApplicationService{
userRepo: userRepo,
userDomainSrv: userDomainSrv,
notificationSrv: notificationSrv,
logger: logger,
}
}
// 业务用例实现
func (s *UserApplicationService) RegisterUser(ctx context.Context, cmd *RegisterUserCommand) error {
// 领域逻辑调用
user, err := domain.NewUser(cmd.Username, cmd.Email, cmd.Password, cmd.FullName)
if err != nil {
return err
}
// 领域规则验证
if !s.userDomainSrv.IsUsernameUnique(user.ID(), user.Username()) {
return errors.New("用户名已存在")
}
if !s.userDomainSrv.IsEmailUnique(user.ID(), user.Email()) {
return errors.New("邮箱已存在")
}
// 持久化
if err := s.userRepo.Save(ctx, user); err != nil {
return err
}
// 外部服务调用
if err := s.notificationSrv.SendWelcomeEmail(user.Email()); err != nil {
s.logger.Error("发送欢迎邮件失败", err)
}
return nil
}
// 3. 基础设施层 - 实现领域层接口
package infrastructure
import "github.com/your-project/internal/domain"
// 数据库用户仓储实现
type DatabaseUserRepository struct {
db *sql.DB
cache *redis.Client
}
// 实现领域层接口
func (r *DatabaseUserRepository) Save(ctx context.Context, user *domain.User) error {
// 数据库操作实现...
}
func (r *DatabaseUserRepository) GetById(ctx context.Context, id domain.UserId) (*domain.User, error) {
// 数据库查询实现...
}
// 用户领域服务实现
type UserDomainServiceImpl struct {
userRepo domain.UserRepository
}
func (s *UserDomainServiceImpl) IsUsernameUnique(userId domain.UserId, username domain.Username) bool {
// 检查用户名唯一性逻辑...
return true
}
// 4. 表示层 - 调用应用层
package presentation
import "github.com/your-project/internal/application"
// HTTP处理器
type UserHTTPHandler struct {
userAppSrv *application.UserApplicationService
}
func (h *UserHTTPHandler) RegisterUser(w http.ResponseWriter, r *http.Request) {
var req RegisterUserRequest
json.NewDecoder(r.Body).Decode(&req)
cmd := &application.RegisterUserCommand{
Username: req.Username,
Email: req.Email,
Password: req.Password,
FullName: req.FullName,
}
if err := h.userAppSrv.RegisterUser(r.Context(), cmd); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
w.WriteHeader(http.StatusCreated)
}
// 依赖注入配置
package main
func main() {
// 创建基础设施依赖
db := sql.Open("mysql", "connection_string")
cache := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
emailSrv := &EmailServiceImpl{}
logger := &LogrusLogger{}
// 创建仓储实现
userRepo := &infrastructure.DatabaseUserRepository{
db: db,
cache: cache,
}
// 创建领域服务实现
userDomainSrv := &infrastructure.UserDomainServiceImpl{
userRepo: userRepo,
}
// 创建应用服务
userAppSrv := &application.UserApplicationService{
userRepo: userRepo,
userDomainSrv: userDomainSrv,
notificationSrv: emailSrv,
logger: logger,
}
// 创建表示层处理器
userHandler := &presentation.UserHTTPHandler{
userAppSrv: userAppSrv,
}
// 启动HTTP服务
http.Handle("/api/users", userHandler)
http.ListenAndServe(":8080", nil)
}
---
03.微服务架构原则
a.单一职责原则
每个微服务应该专注于单一的业务领域，承担明确的业务职责。
b.服务自治
微服务应该具有独立的开发、测试、部署和扩缩容能力。
c.去中心化治理
每个微服务团队可以自主选择技术栈和实现方案，避免技术统一化带来的限制。
d.容错设计
微服务系统应该具备良好的容错能力，能够处理部分服务故障的情况。
e.微服务架构设计示例
---
// 微服务架构设计示例
package microservices
// 微服务定义
type MicroService struct {
name string
version string
endpoints []Endpoint
dependencies []ServiceDependency
healthCheck HealthChecker
}
// 服务端点定义
type Endpoint struct {
path string
method string
handler RequestHandler
middleware []Middleware
timeout time.Duration
}
// 服务依赖定义
type ServiceDependency struct {
serviceName string
endpoint string
protocol Protocol
timeout time.Duration
retryPolicy RetryPolicy
}
// 健康检查接口
type HealthChecker interface {
CheckHealth(ctx context.Context) HealthStatus
}
// 用户微服务
type UserService struct {
base *MicroService
// 业务相关依赖
userRepo UserRepository
authSrv AuthenticationService
notificationSrv NotificationService
}
func NewUserService() *UserService {
service := &UserService{
base: &MicroService{
name: "user-service",
version: "v1.0.0",
dependencies: []ServiceDependency{
{
serviceName: "notification-service",
endpoint: "http://notification-service:8080",
protocol: ProtocolHTTP,
timeout: 5 * time.Second,
retryPolicy: RetryPolicy{
maxRetries: 3,
backoff: 100 * time.Millisecond,
},
},
},
},
}
// 配置服务端点
service.configureEndpoints()
return service
}
func (s *UserService) configureEndpoints() {
// 注册端点
s.base.endpoints = []Endpoint{
{
path: "/api/v1/users",
method: "POST",
handler: s.CreateUser,
middleware: []Middleware{
s.authMiddleware,
s.loggingMiddleware,
s.rateLimitMiddleware,
},
timeout: 10 * time.Second,
},
{
path: "/api/v1/users/{id}",
method: "GET",
handler: s.GetUser,
middleware: []Middleware{
s.authMiddleware,
s.cacheMiddleware,
},
timeout: 5 * time.Second,
},
{
path: "/api/v1/users/{id}",
method: "PUT",
handler: s.UpdateUser,
middleware: []Middleware{
s.authMiddleware,
s.validationMiddleware,
s.auditMiddleware,
},
timeout: 10 * time.Second,
},
}
}
// 容错处理中间件
func (s *UserService) circuitBreakerMiddleware(next http.Handler) http.Handler {
breaker := gobreaker.NewCircuitBreaker(gobreaker.Settings{
Name: "user-service",
MaxRequests: 5,
Interval: 60 * time.Second,
Timeout: 30 * time.Second,
ReadyToTrip: func(counts gobreaker.Counts) bool {
failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
return counts.Requests >= 10 && failureRatio >= 0.6
},
OnStateChange: func(name string, from, to gobreaker.State) {
s.logger.Printf("Circuit breaker %s changed from %s to %s", name, from, to)
},
})
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
result, err := breaker.Execute(func() (interface{}, error) {
var responseRecorder *responseRecorder
ctx := context.WithValue(r.Context(), "response", responseRecorder)
next.ServeHTTP(responseRecorder, r.WithContext(ctx))
return nil, nil
})
if err != nil {
switch err {
case gobreaker.ErrOpenState:
http.Error(w, "Service temporarily unavailable", http.StatusServiceUnavailable)
case gobreaker.ErrTooManyRequests:
http.Error(w, "Service overloaded", http.StatusTooManyRequests)
default:
http.Error(w, "Service error", http.StatusInternalServerError)
}
return
}
})
}
// 重试机制
func (s *UserService) callExternalServiceWithRetry(ctx context.Context, dependency ServiceDependency, request interface{}) (interface{}, error) {
var lastError error
for attempt := 0; attempt <= dependency.retryPolicy.maxRetries; attempt++ {
if attempt > 0 {
backoff := time.Duration(attempt) * dependency.retryPolicy.backoff
select {
case <-time.After(backoff):
case <-ctx.Done():
return nil, ctx.Err()
}
}
resp, err := s.callExternalService(ctx, dependency, request)
if err == nil {
return resp, nil
}
lastError = err
// 如果是不可重试的错误，直接返回
if !isRetryableError(err) {
break
}
s.logger.Printf("调用外部服务失败，第%d次重试: %v", attempt, err)
}
return nil, lastError
}
// 降级处理
func (s *UserService) createUserWithFallback(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error) {
// 尝试正常流程
resp, err := s.createUserNormal(ctx, req)
if err == nil {
return resp, nil
}
s.logger.Errorf("创建用户失败，尝试降级处理: %v", err)
// 降级处理：只保存基本信息，后续异步完善
fallbackResp, fallbackErr := s.createUserFallback(ctx, req)
if fallbackErr != nil {
s.logger.Errorf("降级处理也失败: %v", fallbackErr)
return nil, errors.New("服务暂时不可用，请稍后重试")
}
// 异步队列处理完善用户信息
s.queueUserCompletion(req)
return fallbackResp, nil
}
// 服务发现与负载均衡
type ServiceRegistry struct {
consul *consul.Client
balancer LoadBalancer
cache map[string][]ServiceInstance
mutex sync.RWMutex
}
type ServiceInstance struct {
ID string
Name string
Address string
Port int
Tags []string
Health HealthStatus
}
type LoadBalancer interface {
SelectInstance(instances []ServiceInstance) (*ServiceInstance, error)
}
// 轮询负载均衡
type RoundRobinBalancer struct {
counter map[string]int
mutex sync.Mutex
}
func (b *RoundRobinBalancer) SelectInstance(instances []ServiceInstance) (*ServiceInstance, error) {
if len(instances) == 0 {
return nil, errors.New("没有可用的服务实例")
}
b.mutex.Lock()
defer b.mutex.Unlock()
key := instances[0].Name
count := b.counter[key]
selected := instances[count%len(instances)]
b.counter[key] = count + 1
return &selected, nil
}
// 获取服务实例
func (r *ServiceRegistry) GetServiceInstance(ctx context.Context, serviceName string) (*ServiceInstance, error) {
// 先从缓存获取
r.mutex.RLock()
instances, exists := r.cache[serviceName]
r.mutex.RUnlock()
if !exists {
// 从服务发现中心获取
var err error
instances, err = r.discoverServices(serviceName)
if err != nil {
return nil, err
}
// 更新缓存
r.mutex.Lock()
r.cache[serviceName] = instances
r.mutex.Unlock()
}
// 过滤健康实例
healthyInstances := make([]ServiceInstance, 0)
for _, instance := range instances {
if instance.Health == HealthStatusHealthy {
healthyInstances = append(healthyInstances, instance)
}
}
if len(healthyInstances) == 0 {
return nil, errors.New("没有健康的服务实例")
}
// 负载均衡选择
selected, err := r.balancer.SelectInstance(healthyInstances)
if err != nil {
return nil, err
}
return selected, nil
}
---
04.SOLID原则应用
a.单一职责原则(SRP)
每个类和模块都应该有且仅有一个改变的理由。
b.开闭原则(OCP)
软件实体应该对扩展开放，对修改关闭。
c.里氏替换原则(LSP)
子类型必须能够替换其基类型，而不影响程序的正确性。
d.接口隔离原则(ISP)
客户端不应该被强迫依赖它们不使用的方法。
e.依赖倒置原则(DIP)
高层模块不应该依赖低层模块，两者都应该依赖抽象。
f.SOLID原则应用示例
---
// SOLID原则应用示例
package solid
// 1. 单一职责原则 - 订单处理器和邮件发送分离
type OrderProcessor struct {
orderRepo OrderRepository
notifier NotificationService
}
// 只负责订单处理逻辑
func (p *OrderProcessor) ProcessOrder(order *Order) error {
// 订单处理逻辑
return p.orderRepo.Save(order)
}
// 通知服务只负责发送通知
type NotificationService interface {
SendOrderNotification(order *Order) error
}
// 2. 开闭原则 - 支持扩展新的支付方式
type PaymentProcessor interface {
ProcessPayment(payment *Payment) error
GetPaymentType() string
}
// 具体支付实现
type CreditCardPaymentProcessor struct{}
type AlipayPaymentProcessor struct{}
type WechatPaymentProcessor struct{}
// 支付服务通过注册机制支持扩展
type PaymentService struct {
processors map[string]PaymentProcessor
}
func (s *PaymentService) RegisterProcessor(processor PaymentProcessor) {
s.processors[processor.GetPaymentType()] = processor
}
func (s *PaymentService) ProcessPayment(payment *Payment) error {
processor, exists := s.processors[payment.Type]
if !exists {
return fmt.Errorf("不支持的支付方式: %s", payment.Type)
}
return processor.ProcessPayment(payment)
}
// 3. 里氏替换原则 - 日志记录器接口和实现
type Logger interface {
Log(message string)
LogWithLevel(level LogLevel, message string)
}
type ConsoleLogger struct{}
type FileLogger struct {
filePath string
}
type DatabaseLogger struct {
db *sql.DB
}
// 任何Logger实现都可以替换使用
func ProcessData(data []Data, logger Logger) error {
logger.LogWithLevel(LogLevelInfo, "开始处理数据")
for _, item := range data {
if err := processItem(item); err != nil {
logger.LogWithLevel(LogLevelError, fmt.Sprintf("处理数据失败: %v", err))
return err
}
}
logger.LogWithLevel(LogLevelInfo, "数据处理完成")
return nil
}
// 4. 接口隔离原则 - 避免大接口
// 不好的设计 - 大接口
type UserRepository interface {
Create(user *User) error
GetById(id string) (*User, error)
GetByEmail(email string) (*User, error)
Update(user *User) error
Delete(id string) error
Search(criteria SearchCriteria) ([]*User, error)
Count(criteria SearchCriteria) (int64, error)
BatchCreate(users []*User) error
BatchUpdate(users []*User) error
BatchDelete(ids []string) error
}
// 好的设计 - 接口隔离
type UserReader interface {
GetById(id string) (*User, error)
GetByEmail(email string) (*User, error)
Search(criteria SearchCriteria) ([]*User, error)
Count(criteria SearchCriteria) (int64, error)
}
type UserWriter interface {
Create(user *User) error
Update(user *User) error
Delete(id string) error
}
type UserBatchWriter interface {
BatchCreate(users []*User) error
BatchUpdate(users []*User) error
BatchDelete(ids []string) error
}
// 组合接口
type UserRepository interface {
UserReader
UserWriter
UserBatchWriter
}
// 5. 依赖倒置原则 - 高层模块依赖抽象
// 高层模块 - 用户服务
type UserService struct {
userReader UserReader // 依赖抽象
userWriter UserWriter // 依赖抽象
notifier NotificationService // 依赖抽象
validator Validator // 依赖抽象
}
func NewUserService(
reader UserReader,
writer UserWriter,
notifier NotificationService,
validator Validator,
) *UserService {
return &UserService{
userReader: reader,
userWriter: writer,
notifier: notifier,
validator: validator,
}
}
func (s *UserService) CreateUser(cmd *CreateUserCommand) error {
// 使用验证器抽象
if err := s.validator.Validate(cmd); err != nil {
return err
}
user := &User{
Username: cmd.Username,
Email: cmd.Email,
}
// 使用写入抽象
if err := s.userWriter.Create(user); err != nil {
return err
}
// 使用通知抽象
return s.notifier.SendWelcomeNotification(user)
}
// 验证器接口
type Validator interface {
Validate(obj interface{}) error
}
// 具体验证器实现
type CreateUserValidator struct{}
type UpdateUserValidator struct{}
func (v *CreateUserValidator) Validate(obj interface{}) error {
cmd, ok := obj.(*CreateUserCommand)
if !ok {
return errors.New("类型错误")
}
if cmd.Username == "" {
return errors.New("用户名不能为空")
}
if cmd.Email == "" {
return errors.New("邮箱不能为空")
}
return nil
}
// 依赖注入容器
type Container struct {
services map[reflect.Type]interface{}
mutex sync.RWMutex
}
func NewContainer() *Container {
return &Container{
services: make(map[reflect.Type]interface{}),
}
}
func (c *Container) Register(service interface{}) {
c.mutex.Lock()
defer c.mutex.Unlock()
serviceType := reflect.TypeOf(service)
c.services[serviceType] = service
}
func (c *Container) Resolve(serviceType reflect.Type) (interface{}, error) {
c.mutex.RLock()
service, exists := c.services[serviceType]
c.mutex.RUnlock()
if !exists {
return nil, fmt.Errorf("服务未注册: %v", serviceType)
}
return service, nil
}
// 配置依赖注入
func setupDependencies() *Container {
container := NewContainer()
// 注册具体实现
container.Register(&DatabaseUserReader{})
container.Register(&DatabaseUserWriter{})
container.Register(&EmailNotificationService{})
container.Register(&CreateUserValidator{})
return container
}
// 应用启动
func main() {
container := setupDependencies()
// 解析依赖
userReader, _ := container.Resolve(reflect.TypeOf((*UserReader)(nil)).Elem())
userWriter, _ := container.Resolve(reflect.TypeOf((*UserWriter)(nil)).Elem())
notifier, _ := container.Resolve(reflect.TypeOf((*NotificationService)(nil)).Elem())
validator, _ := container.Resolve(reflect.TypeOf((*Validator)(nil)).Elem())
// 创建用户服务
userService := NewUserService(
userReader.(UserReader),
userWriter.(UserWriter),
notifier.(NotificationService),
validator.(Validator),
)
// 使用服务
err := userService.CreateUser(&CreateUserCommand{
Username: "testuser",
Email: "[email protected]",
})
if err != nil {
log.Printf("创建用户失败: %v", err)
}
}
---
1.7 技术特性
01.高性能网络通信
a.gRPC框架集成
a.基于HTTP/2协议
支持多路复用、头部压缩、服务器推送等特性，大幅提升网络传输效率。
b.Protocol Buffers序列化
使用二进制格式进行数据序列化，相比JSON格式性能提升3-5倍。
c.四种调用模式
支持一元调用、客户端流式、服务端流式和双向流式四种RPC调用模式。
d.gRPC服务示例
---
// gRPC高性能服务示例
package grpc
import (
"context"
"net"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/keepalive"
"google.golang.org/grpc/reflection"
)
// gRPC服务器配置
type GRPCServerConfig struct {
Address string `json:"address"`
MaxRecvMsgSize int `json:"max_recv_msg_size"`
MaxSendMsgSize int `json:"max_send_msg_size"`
ReadTimeout time.Duration `json:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout"`
KeepaliveParams keepalive.ServerParameters
}
// 高性能gRPC服务器
func NewHighPerformanceGRPCServer(config GRPCServerConfig) (*grpc.Server, error) {
// 设置服务器选项
opts := []grpc.ServerOption{
// 消息大小限制
grpc.MaxRecvMsgSize(config.MaxRecvMsgSize),
grpc.MaxSendMsgSize(config.MaxSendMsgSize),
// 连接参数
grpc.KeepaliveParams(config.KeepaliveParams),
grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
MinTime: 10 * time.Second, // 最小ping间隔
PermitWithoutStream: true, // 允许无流ping
}),
// 流控制
grpc.InitialWindowSize(64 * 1024), // 64KB初始窗口
grpc.InitialConnWindowSize(128 * 1024), // 128KB连接窗口
grpc.WriteBufferSize(32 * 1024), // 32KB写缓冲
grpc.ReadBufferSize(32 * 1024), // 32KB读缓冲
// 拦截器
grpc.UnaryInterceptor(unaryServerInterceptor()),
grpc.StreamInterceptor(streamServerInterceptor()),
grpc.ChainUnaryInterceptor(
loggingInterceptor(),
metricsInterceptor(),
authInterceptor(),
recoveryInterceptor(),
),
grpc.ChainStreamInterceptor(
loggingStreamInterceptor(),
metricsStreamInterceptor(),
authStreamInterceptor(),
),
}
server := grpc.NewServer(opts...)
// 启用反射（用于调试）
reflection.Register(server)
return server, nil
}
// 一元调用拦截器
func unaryServerInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
start := time.Now()
// 记录请求开始
log.Printf("开始处理一元调用: %s", info.FullMethod)
// 执行业务逻辑
resp, err := handler(ctx, req)
// 记录请求完成
duration := time.Since(start)
log.Printf("完成一元调用: %s, 耗时: %v, 错误: %v", info.FullMethod, duration, err)
// 记录性能指标
recordMetrics(info.FullMethod, duration, err)
return resp, err
}
}
// 流式调用拦截器
func streamServerInterceptor() grpc.StreamServerInterceptor {
return func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
start := time.Now()
// 包装流以监控流量
wrappedStream := &monitoredStream{
ServerStream: ss,
info: info,
startTime: start,
}
log.Printf("开始处理流式调用: %s", info.FullMethod)
err := handler(srv, wrappedStream)
duration := time.Since(start)
log.Printf("完成流式调用: %s, 耗时: %v, 错误: %v", info.FullMethod, duration, err)
recordMetrics(info.FullMethod, duration, err)
return err
}
}
// 监控流量的包装器
type monitoredStream struct {
grpc.ServerStream
info *grpc.StreamServerInfo
startTime time.Time
bytesRead int64
bytesWrite int64
}
func (s *monitoredStream) RecvMsg(m interface{}) error {
err := s.ServerStream.RecvMsg(m)
if err == nil {
s.bytesRead += int64(sizeOf(m))
}
return err
}
func (s *monitoredStream) SendMsg(m interface{}) error {
err := s.ServerStream.SendMsg(m)
if err == nil {
s.bytesWrite += int64(sizeOf(m))
}
return err
}
// 客户端连接池
type GRPCClientPool struct {
connections map[string]*grpc.ClientConn
mutex sync.RWMutex
config GRPCClientPoolConfig
}
type GRPCClientPoolConfig struct {
MaxConnections int `json:"max_connections"`
IdleTimeout time.Duration `json:"idle_timeout"`
DialTimeout time.Duration `json:"dial_timeout"`
Keepalive keepalive.ClientParameters
}
func NewGRPCClientPool(config GRPCClientPoolConfig) *GRPCClientPool {
return &GRPCClientPool{
connections: make(map[string]*grpc.ClientConn),
config: config,
}
}
func (p *GRPCClientPool) GetConnection(address string) (*grpc.ClientConn, error) {
p.mutex.RLock()
conn, exists := p.connections[address]
p.mutex.RUnlock()
if exists {
// 检查连接状态
state := conn.GetState()
if state == connectivity.Ready {
return conn, nil
} else if state == connectivity.TransientFailure || state == connectivity.Shutdown {
// 连接不可用，移除并重新创建
p.removeConnection(address)
}
}
// 创建新连接
return p.createConnection(address)
}
func (p *GRPCClientPool) createConnection(address string) (*grpc.ClientConn, error) {
ctx, cancel := context.WithTimeout(context.Background(), p.config.DialTimeout)
defer cancel()
opts := []grpc.DialOption{
grpc.WithInsecure(), // 生产环境应使用TLS
grpc.WithKeepaliveParams(p.config.Keepalive),
grpc.WithInitialWindowSize(64 * 1024),
grpc.WithInitialConnWindowSize(128 * 1024),
grpc.WithWriteBufferSize(32 * 1024),
grpc.WithReadBufferSize(32 * 1024),
grpc.WithUnaryInterceptor(unaryClientInterceptor()),
grpc.WithStreamInterceptor(streamClientInterceptor()),
grpc.WithBlock(),
}
conn, err := grpc.DialContext(ctx, address, opts...)
if err != nil {
return nil, fmt.Errorf("创建gRPC连接失败: %s", err.Error())
}
p.mutex.Lock()
p.connections[address] = conn
p.mutex.Unlock()
log.Printf("创建新的gRPC连接: %s", address)
return conn, nil
}
func (p *GRPCClientPool) removeConnection(address string) {
p.mutex.Lock()
defer p.mutex.Unlock()
if conn, exists := p.connections[address]; exists {
conn.Close()
delete(p.connections, address)
log.Printf("移除gRPC连接: %s", address)
}
}
// 客户端拦截器
func unaryClientInterceptor() grpc.UnaryClientInterceptor {
return func(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
start := time.Now()
// 添加追踪信息
ctx = addTracingHeaders(ctx, method)
err := invoker(ctx, method, req, reply, cc, opts...)
duration := time.Since(start)
log.Printf("客户端一元调用: %s, 耗时: %v, 错误: %v", method, duration, err)
return err
}
}
func streamClientInterceptor() grpc.StreamClientInterceptor {
return func(ctx context.Context, desc *grpc.StreamDesc, cc *grpc.ClientConn, method string, streamer grpc.Streamer, opts ...grpc.CallOption) (grpc.ClientStream, error) {
// 添加追踪信息
ctx = addTracingHeaders(ctx, method)
stream, err := streamer(ctx, desc, cc, method, opts...)
if err != nil {
return nil, err
}
return &monitoredClientStream{
ClientStream: stream,
method: method,
startTime: time.Now(),
}, nil
}
}
type monitoredClientStream struct {
grpc.ClientStream
method string
startTime time.Time
}
func (s *monitoredClientStream) SendMsg(m interface{}) error {
err := s.ClientStream.SendMsg(m)
if err != nil {
log.Printf("客户端流发送失败: %s, 错误: %v", s.method, err)
}
return err
}
func (s *monitoredClientStream) RecvMsg(m interface{}) error {
err := s.ClientStream.RecvMsg(m)
if err != nil && err != io.EOF {
log.Printf("客户端流接收失败: %s, 错误: %v", s.method, err)
}
return err
}
func (s *monitoredClientStream) CloseSend() error {
duration := time.Since(s.startTime)
log.Printf("客户端流关闭: %s, 总耗时: %v", s.method, duration)
return s.ClientStream.CloseSend()
}
---
b.HTTP服务优化
a.连接复用
使用Keep-Alive连接池，减少TCP连接建立和销毁的开销。
b.压缩传输
支持Gzip、Deflate等压缩算法，减少网络传输数据量。
c.缓存策略
实现HTTP缓存机制，减少重复请求的计算和数据库访问。
d.HTTP服务优化示例
---
// HTTP服务优化示例
package http
import (
"compress/gzip"
"context"
"io"
"net/http"
"strings"
"time"
"github.com/gin-gonic/gin"
"github.com/gin-contrib/cors"
)
// 高性能HTTP服务器配置
type HTTPServerConfig struct {
Address string `json:"address"`
ReadTimeout time.Duration `json:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout"`
IdleTimeout time.Duration `json:"idle_timeout"`
MaxHeaderBytes int `json:"max_header_bytes"`
GzipCompression bool `json:"gzip_compression"`
CORSConfig CORSConfig `json:"cors_config"`
}
type CORSConfig struct {
AllowOrigins []string `json:"allow_origins"`
AllowMethods []string `json:"allow_methods"`
AllowHeaders []string `json:"allow_headers"`
ExposeHeaders []string `json:"expose_headers"`
AllowCredentials bool `json:"allow_credentials"`
MaxAge int `json:"max_age"`
}
// 创建优化的Gin引擎
func NewOptimizedGinEngine(config HTTPServerConfig) *gin.Engine {
// 设置Gin模式
gin.SetMode(gin.ReleaseMode)
engine := gin.New()
// 添加中间件
engine.Use(gin.Recovery()) // 恢复中间件
engine.Use(loggingMiddleware(config))
engine.Use(metricsMiddleware())
engine.Use(rateLimitMiddleware())
// 添加CORS支持
if config.CORSConfig.AllowOrigins != nil {
corsConfig := cors.DefaultConfig()
corsConfig.AllowOrigins = config.CORSConfig.AllowOrigins
corsConfig.AllowMethods = config.CORSConfig.AllowMethods
corsConfig.AllowHeaders = config.CORSConfig.AllowHeaders
corsConfig.ExposeHeaders = config.CORSConfig.ExposeHeaders
corsConfig.AllowCredentials = config.CORSConfig.AllowCredentials
corsConfig.MaxAge = time.Duration(config.CORSConfig.MaxAge) * time.Second
engine.Use(cors.New(corsConfig))
}
// 添加Gzip压缩
if config.GzipCompression {
gin.WrapHandler(gzipHandler())
}
// 配置模板缓存
engine.LoadHTMLGlob("templates/*")
return engine
}
// 高性能HTTP服务器
func NewHighPerformanceHTTPServer(engine *gin.Engine, config HTTPServerConfig) *http.Server {
server := &http.Server{
Addr: config.Address,
Handler: engine,
ReadTimeout: config.ReadTimeout,
WriteTimeout: config.WriteTimeout,
IdleTimeout: config.IdleTimeout,
MaxHeaderBytes: config.MaxHeaderBytes,
}
// 配置TCP参数
server.ConnState = func(conn net.Conn, state http.ConnState) {
switch state {
case http.StateNew:
log.Printf("新连接建立: %s", conn.RemoteAddr())
case http.StateClosed:
log.Printf("连接关闭: %s", conn.RemoteAddr())
case http.StateHijacked:
log.Printf("连接被劫持: %s", conn.RemoteAddr())
}
}
return server
}
// Gzip压缩中间件
func gzipHandler() func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 检查客户端是否支持gzip
if !strings.Contains(r.Header.Get("Accept-Encoding"), "gzip") {
next.ServeHTTP(w, r)
return
}
// 设置响应头
w.Header().Set("Content-Encoding", "gzip")
w.Header().Set("Vary", "Accept-Encoding")
// 创建gzip写入器
gz := gzip.NewWriter(w)
defer gz.Close()
// 包装响应写入器
gzw := &gzipResponseWriter{
ResponseWriter: w,
writer: gz,
}
next.ServeHTTP(gzw, r)
})
}
}
type gzipResponseWriter struct {
http.ResponseWriter
writer *gzip.Writer
}
func (w *gzipResponseWriter) Write(data []byte) (int, error) {
return w.writer.Write(data)
}
// 缓存中间件
func cacheMiddleware(cache CacheStore) gin.HandlerFunc {
return func(c *gin.Context) {
// 检查请求方法
if c.Request.Method != "GET" {
c.Next()
return
}
// 生成缓存键
key := generateCacheKey(c)
// 尝试从缓存获取
if cached, found := cache.Get(key); found {
c.Header("X-Cache", "HIT")
c.JSON(http.StatusOK, cached)
c.Abort()
return
}
// 执行处理器
c.Next()
// 如果请求成功，缓存响应
if c.Writer.Status() == http.StatusOK {
cache.Set(key, c.Keys["response"], 5*time.Minute)
c.Header("X-Cache", "MISS")
}
}
}
// 连接池中间件
func connectionPoolMiddleware() gin.HandlerFunc {
var pool = &sync.Pool{
New: func() interface{} {
return make([]byte, 32*1024) // 32KB缓冲区
},
}
return func(c *gin.Context) {
// 从池中获取缓冲区
buffer := pool.Get().([]byte)
// 设置到上下文中供处理器使用
c.Set("buffer", buffer)
c.Next()
// 归还缓冲区到池中
pool.Put(buffer)
}
}
// 性能监控中间件
func metricsMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
// 记录请求开始
c.Set("start_time", start)
// 执行处理器
c.Next()
// 计算处理时间
duration := time.Since(start)
// 记录性能指标
recordHTTPMetrics(c, duration)
// 设置响应头
c.Header("X-Response-Time", duration.String())
c.Header("X-Request-ID", c.GetString("request_id"))
}
}
// 记录HTTP指标
func recordHTTPMetrics(c *gin.Context, duration time.Duration) {
labels := map[string]string{
"method": c.Request.Method,
"path": c.FullPath(),
"status": strconv.Itoa(c.Writer.Status()),
}
// 记录请求计数
requestCount.With(labels).Inc()
// 记录响应时间
requestDuration.With(labels).Observe(duration.Seconds())
// 记录错误计数
if c.Writer.Status() >= 400 {
errorCount.With(labels).Inc()
}
}
// 速率限制中间件
func rateLimitMiddleware() gin.HandlerFunc {
limiter := rate.NewLimiter(rate.Every(time.Second), 1000) // 每秒1000个请求
return func(c *gin.Context) {
if !limiter.Allow() {
c.JSON(http.StatusTooManyRequests, gin.H{
"error": "请求过于频繁，请稍后重试",
})
c.Abort()
return
}
c.Next()
}
}
// 日志中间件
func loggingMiddleware(config HTTPServerConfig) gin.HandlerFunc {
return func(c *gin.Context) {
// 生成请求ID
requestID := generateRequestID()
c.Set("request_id", requestID)
start := time.Now()
path := c.Request.URL.Path
raw := c.Request.URL.RawQuery
// 记录请求开始
log.Printf("[%s] 开始处理请求: %s %s", requestID, c.Request.Method, path)
// 执行处理器
c.Next()
// 计算处理时间
latency := time.Since(start)
// 构建完整路径
if raw != "" {
path = path + "?" + raw
}
// 记录请求完成
status := c.Writer.Status()
log.Printf("[%s] 完成请求: %s %s %d %v %s",
requestID,
c.Request.Method,
path,
status,
latency,
c.ClientIP(),
)
}
}
// 健康检查处理器
func healthCheckHandler(c *gin.Context) {
status := map[string]interface{}{
"status": "healthy",
"timestamp": time.Now().Unix(),
"version": "1.0.0",
"checks": map[string]interface{}{
"database": checkDatabase(),
"redis": checkRedis(),
"storage": checkStorage(),
},
}
// 检查所有依赖服务状态
allHealthy := true
for _, check := range status["checks"].(map[string]interface{}) {
if checkCheck := check.(map[string]interface{}); checkCheck["status"] != "healthy" {
allHealthy = false
break
}
}
if allHealthy {
c.JSON(http.StatusOK, status)
} else {
c.JSON(http.StatusServiceUnavailable, status)
}
}
// 数据库健康检查
func checkDatabase() map[string]interface{} {
db := getDatabaseConnection()
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err := db.PingContext(ctx)
if err != nil {
return map[string]interface{}{
"status": "unhealthy",
"error": err.Error(),
"timeout": "5s",
}
}
return map[string]interface{}{
"status": "healthy",
"latency": "1ms",
}
}
// Redis健康检查
func checkRedis() map[string]interface{} {
redis := getRedisClient()
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
_, err := redis.Ping(ctx).Result()
if err != nil {
return map[string]interface{}{
"status": "unhealthy",
"error": err.Error(),
"timeout": "3s",
}
}
return map[string]interface{}{
"status": "healthy",
"latency": "0.5ms",
}
}
// 存储健康检查
func checkStorage() map[string]interface{} {
storage := getStorageClient()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// 测试文件读写
testFile := "/health_check_" + time.Now().Format("20060102150405") + ".tmp"
err := storage.WriteFile(ctx, testFile, []byte("health check"))
if err != nil {
return map[string]interface{}{
"status": "unhealthy",
"error": err.Error(),
"timeout": "10s",
}
}
_, err = storage.ReadFile(ctx, testFile)
if err != nil {
return map[string]interface{}{
"status": "unhealthy",
"error": err.Error(),
"timeout": "10s",
}
}
storage.DeleteFile(ctx, testFile)
return map[string]interface{}{
"status": "healthy",
"latency": "2ms",
}
}
---
02.可观测性支持
a.指标监控
集成Prometheus监控指标，提供HTTP请求、gRPC调用、业务指标等多维度监控数据。
b.链路追踪
支持OpenTelemetry标准，实现分布式系统的请求链路追踪和性能分析。
c.结构化日志
提供结构化日志记录能力，支持多种输出格式和日志级别控制。
d.可观测性示例
---
// 可观测性集成示例
package observability
import (
"context"
"time"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/jaeger"
"go.opentelemetry.io/otel/exporters/prometheus"
"go.opentelemetry.io/otel/metric"
"go.opentelemetry.io/otel/propagation"
"go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
"go.opentelemetry.io/otel/sdk/trace"
semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
"github.com/prometheus/client_golang/prometheus/promhttp"
)
// 可观测性配置
type ObservabilityConfig struct {
ServiceName string `json:"service_name"`
ServiceVersion string `json:"service_version"`
Environment string `json:"environment"`
JaegerEndpoint string `json:"jaeger_endpoint"`
PrometheusPort int `json:"prometheus_port"`
LogLevel string `json:"log_level"`
Labels map[string]string `json:"labels"`
}
// 初始化可观测性
func InitObservability(ctx context.Context, config ObservabilityConfig) (func(), error) {
// 创建资源
res, err := resource.New(ctx,
resource.WithAttributes(
semconv.ServiceNameKey.String(config.ServiceName),
semconv.ServiceVersionKey.String(config.ServiceVersion),
semconv.DeploymentEnvironmentKey.String(config.Environment),
),
)
if err != nil {
return nil, fmt.Errorf("创建资源失败: %s", err.Error())
}
// 初始化链路追踪
tracerProvider, err := initTracing(ctx, config, res)
if err != nil {
return nil, fmt.Errorf("初始化链路追踪失败: %s", err.Error())
}
// 初始化指标监控
meterProvider, err := initMetrics(ctx, config, res)
if err != nil {
return nil, fmt.Errorf("初始化指标监控失败: %s", err.Error())
}
// 启动Prometheus HTTP服务器
go startPrometheusServer(config.PrometheusPort)
return func() {
// 关闭链路追踪
if err := tracerProvider.Shutdown(ctx); err != nil {
log.Printf("关闭链路追踪失败: %v", err)
}
// 关闭指标监控
if err := meterProvider.Shutdown(ctx); err != nil {
log.Printf("关闭指标监控失败: %v", err)
}
}, nil
}
// 初始化链路追踪
func initTracing(ctx context.Context, config ObservabilityConfig, res *resource.Resource) (*trace.TracerProvider, error) {
// 创建Jaeger导出器
exp, err := jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(config.JaegerEndpoint)))
if err != nil {
return nil, fmt.Errorf("创建Jaeger导出器失败: %s", err.Error())
}
// 创建采样器
sampler := trace.TraceIDRatioBased(0.1) // 10%采样率
// 创建追踪器提供者
tp := trace.NewTracerProvider(
trace.WithBatcher(exp),
trace.WithResource(res),
trace.WithSampler(sampler),
)
// 注册为全局追踪器提供者
otel.SetTracerProvider(tp)
// 设置全局传播器
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
propagation.TraceContext{},
propagation.Baggage{},
))
return tp, nil
}
// 初始化指标监控
func initMetrics(ctx context.Context, config ObservabilityConfig, res *resource.Resource) (*metric.MeterProvider, error) {
// 创建Prometheus导出器
exp, err := prometheus.New()
if err != nil {
return nil, fmt.Errorf("创建Prometheus导出器失败: %s", err.Error())
}
// 创建计量器提供者
mp := metric.NewMeterProvider(
metric.WithResource(res),
metric.WithReader(exp),
)
// 注册为全局计量器提供者
otel.SetMeterProvider(mp)
return mp, nil
}
// 启动Prometheus HTTP服务器
func startPrometheusServer(port int) {
mux := http.NewServeMux()
mux.Handle("/metrics", promhttp.Handler())
server := &http.Server{
Addr: fmt.Sprintf(":%d", port),
Handler: mux,
}
log.Printf("Prometheus指标服务器启动在端口: %d", port)
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Printf("Prometheus服务器错误: %v", err)
}
}
// 业务指标定义
var (
// HTTP请求指标
httpRequestsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "HTTP请求总数",
},
[]string{"method", "path", "status_code", "service"},
)
httpRequestDuration = prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP请求持续时间",
Buckets: prometheus.DefBuckets,
},
[]string{"method", "path", "status_code", "service"},
)
// gRPC指标
grpcRequestsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "grpc_requests_total",
Help: "gRPC请求总数",
},
[]string{"method", "status_code", "service"},
)
grpcRequestDuration = prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "grpc_request_duration_seconds",
Help: "gRPC请求持续时间",
Buckets: prometheus.DefBuckets,
},
[]string{"method", "status_code", "service"},
)
// 业务指标
userRegistrationsTotal = prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "user_registrations_total",
Help: "用户注册总数",
},
[]string{"source", "plan"},
)
orderValueHistogram = prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "order_value_histogram",
Help: "订单金额分布",
Buckets: []float64{10, 50, 100, 500, 1000, 5000, 10000},
},
[]string{"currency", "payment_method"},
)
)
// 注册指标
func init() {
prometheus.MustRegister(httpRequestsTotal)
prometheus.MustRegister(httpRequestDuration)
prometheus.MustRegister(grpcRequestsTotal)
prometheus.MustRegister(grpcRequestDuration)
prometheus.MustRegister(userRegistrationsTotal)
prometheus.MustRegister(orderValueHistogram)
}
// 指标中间件
func metricsMiddleware(serviceName string) gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
// 执行处理器
c.Next()
// 记录请求指标
duration := time.Since(start)
status := c.Writer.Status()
method := c.Request.Method
path := c.FullPath()
httpRequestsTotal.WithLabelValues(method, path, fmt.Sprintf("%d", status), serviceName).Inc()
httpRequestDuration.WithLabelValues(method, path, fmt.Sprintf("%d", status), serviceName).Observe(duration.Seconds())
}
}
// 链路追踪中间件
func tracingMiddleware(serviceName string) gin.HandlerFunc {
return func(c *gin.Context) {
tracer := otel.Tracer(serviceName)
// 创建span
spanCtx, span := tracer.Start(
c.Request.Context(),
fmt.Sprintf("%s %s", c.Request.Method, c.FullPath()),
trace.WithAttributes(
attribute.String("http.method", c.Request.Method),
attribute.String("http.url", c.Request.URL.String()),
attribute.String("http.user_agent", c.Request.UserAgent()),
attribute.String("http.remote_addr", c.Request.RemoteAddr),
),
)
// 设置span到上下文
c.Request = c.Request.WithContext(spanCtx)
// 执行处理器
c.Next()
// 设置响应属性
span.SetAttributes(
attribute.Int("http.status_code", c.Writer.Status()),
)
// 根据状态码设置span状态
if c.Writer.Status() >= 400 {
span.SetStatus(trace.StatusError, "HTTP error")
} else {
span.SetStatus(trace.StatusOk, "HTTP success")
}
span.End()
}
}
// 业务指标记录
func RecordUserRegistration(source, plan string) {
userRegistrationsTotal.WithLabelValues(source, plan).Inc()
}
func RecordOrderValue(amount float64, currency, paymentMethod string) {
orderValueHistogram.WithLabelValues(currency, paymentMethod).Observe(amount)
}
// 结构化日志记录器
type StructuredLogger struct {
logger *zap.Logger
}
func NewStructuredLogger(level string) *StructuredLogger {
var config zap.Config
switch level {
case "debug":
config = zap.NewDevelopmentConfig()
default:
config = zap.NewProductionConfig()
}
logger, err := config.Build()
if err != nil {
log.Fatalf("创建日志记录器失败: %v", err)
}
return &StructuredLogger{
logger: logger,
}
}
func (l *StructuredLogger) LogRequest(ctx context.Context, method, path string, statusCode int, duration time.Duration) {
span := trace.SpanFromContext(ctx)
traceID := span.SpanContext().TraceID().String()
spanID := span.SpanContext().SpanID().String()
l.logger.Info("HTTP请求",
zap.String("trace_id", traceID),
zap.String("span_id", spanID),
zap.String("method", method),
zap.String("path", path),
zap.Int("status_code", statusCode),
zap.Duration("duration", duration),
zap.Time("timestamp", time.Now()),
)
}
func (l *StructuredLogger) LogError(ctx context.Context, err error, msg string, fields ...zap.Field) {
span := trace.SpanFromContext(ctx)
traceID := span.SpanContext().TraceID().String()
spanID := span.SpanContext().SpanID().String()
allFields := append([]zap.Field{
zap.String("trace_id", traceID),
zap.String("span_id", spanID),
zap.Error(err),
zap.Time("timestamp", time.Now()),
}, fields...)
l.logger.Error(msg, allFields...)
}
func (l *StructuredLogger) LogBusinessEvent(ctx context.Context, event string, userID string, fields ...zap.Field) {
span := trace.SpanFromContext(ctx)
traceID := span.SpanContext().TraceID().String()
spanID := span.SpanContext().SpanID().String()
allFields := append([]zap.Field{
zap.String("trace_id", traceID),
zap.String("span_id", spanID),
zap.String("event", event),
zap.String("user_id", userID),
zap.Time("timestamp", time.Now()),
}, fields...)
l.logger.Info("业务事件", allFields...)
}
---
03.配置热更新
a.动态配置加载
支持从文件、环境变量、配置中心等多种数据源动态加载配置。
b.配置变更监听
提供配置变更事件通知机制，支持业务逻辑实时响应配置变化。
c.配置验证
支持配置项的类型检查、格式验证和业务规则验证。
d.配置热更新示例
---
// 配置热更新示例
package config
import (
"context"
"reflect"
"sync"
"time"
"github.com/fsnotify/fsnotify"
"github.com/spf13/viper"
"github.com/nacos-group/nacos-sdk-go/clients/config_client"
)
// 配置管理器
type ConfigManager struct {
config *Config
mutex sync.RWMutex
watchers map[string][]ConfigWatcher
fileWatcher *fsnotify.Watcher
nacosClient config_client.IConfigClient
logger Logger
validationRules map[string]ValidationRule
}
// 配置变更监听器
type ConfigWatcher interface {
OnConfigChanged(key string, oldValue, newValue interface{})
}
// 配置结构
type Config struct {
Server ServerConfig `mapstructure:"server" validate:"required"`
Database DatabaseConfig `mapstructure:"database" validate:"required"`
Redis RedisConfig `mapstructure:"redis" validate:"required"`
Log LogConfig `mapstructure:"log" validate:"required"`
Auth AuthConfig `mapstructure:"auth" validate:"required"`
}
type ServerConfig struct {
HTTP ServerHTTPConfig `mapstructure:"http" validate:"required"`
GRPC ServerGRPCConfig `mapstructure:"grpc" validate:"required"`
}
type DatabaseConfig struct {
Driver string `mapstructure:"driver" validate:"required,oneof=mysql postgres sqlite"`
Source string `mapstructure:"source" validate:"required"`
MaxOpenConns int `mapstructure:"max_open_conns" validate:"min=1,max=100"`
MaxIdleConns int `mapstructure:"max_idle_conns" validate:"min=1,max=10"`
ConnMaxLifetime time.Duration `mapstructure:"conn_max_lifetime" validate:"min=1s"`
}
// 验证规则接口
type ValidationRule interface {
Validate(key string, value interface{}) error
}
// 端口号验证规则
type PortValidationRule struct{}
func (r *PortValidationRule) Validate(key string, value interface{}) error {
port, ok := value.(int)
if !ok {
return fmt.Errorf("端口必须是整数")
}
if port < 1 || port > 65535 {
return fmt.Errorf("端口必须在1-65535范围内")
}
return nil
}
// 邮箱格式验证规则
type EmailValidationRule struct{}
func (r *EmailValidationRule) Validate(key string, value interface{}) error {
email, ok := value.(string)
if !ok {
return fmt.Errorf("邮箱必须是字符串")
}
pattern := `^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`
matched, err := regexp.MatchString(pattern, email)
if err != nil || !matched {
return fmt.Errorf("邮箱格式不正确")
}
return nil
}
// 创建配置管理器
func NewConfigManager(configPath string, logger Logger) (*ConfigManager, error) {
cm := &ConfigManager{
watchers: make(map[string][]ConfigWatcher),
logger: logger,
validationRules: make(map[string]ValidationRule),
}
// 注册验证规则
cm.registerValidationRules()
// 初始化Viper
v := viper.New()
v.SetConfigFile(configPath)
v.SetConfigType("yaml")
// 设置默认值
cm.setDefaults(v)
// 读取配置文件
if err := v.ReadInConfig(); err != nil {
return nil, fmt.Errorf("读取配置文件失败: %s", err.Error())
}
// 解析配置
var config Config
if err := v.Unmarshal(&config); err != nil {
return nil, fmt.Errorf("解析配置失败: %s", err.Error())
}
// 验证配置
if err := cm.validateConfig(&config); err != nil {
return nil, fmt.Errorf("配置验证失败: %s", err.Error())
}
cm.config = &config
// 设置配置变更监听
v.WatchConfig(cm.createViperWatcher())
return cm, nil
}
// 注册验证规则
func (cm *ConfigManager) registerValidationRules() {
cm.validationRules["server.http.addr"] = &PortValidationRule{}
cm.validationRules["server.grpc.addr"] = &PortValidationRule{}
cm.validationRules["auth.jwt_issuer"] = &EmailValidationRule{}
}
// 设置默认值
func (cm *ConfigManager) setDefaults(v *viper.Viper) {
v.SetDefault("server.http.addr", ":8080")
v.SetDefault("server.http.timeout", "30s")
v.SetDefault("server.grpc.addr", ":9090")
v.SetDefault("server.grpc.timeout", "30s")
v.SetDefault("database.max_open_conns", 10)
v.SetDefault("database.max_idle_conns", 5)
v.SetDefault("database.conn_max_lifetime", "1h")
v.SetDefault("redis.addr", "localhost:6379")
v.SetDefault("redis.db", 0)
v.SetDefault("log.level", "info")
v.SetDefault("auth.jwt_secret", "default-secret")
v.SetDefault("auth.token_expire", "24h")
}
// 验证配置
func (cm *ConfigManager) validateConfig(config *Config) error {
// 使用validator库进行结构体验证
validate := validator.New()
if err := validate.Struct(config); err != nil {
return err
}
// 自定义验证规则
if err := cm.validateCustomRules(config); err != nil {
return err
}
return nil
}
// 自定义规则验证
func (cm *ConfigManager) validateCustomRules(config *Config) error {
// 验证数据库连接字符串格式
if config.Database.Driver == "mysql" {
pattern := `^\w+:\w+@tcp\(.+\)/\w+(\?.*)?$`
matched, err := regexp.MatchString(pattern, config.Database.Source)
if err != nil || !matched {
return fmt.Errorf("MySQL连接字符串格式不正确")
}
}
return nil
}
// 创建Viper配置变更监听器
func (cm *ConfigManager) createViperWatcher() fsnotify.Watcher {
return fsnotify.Watcher{
Handler: func(e fsnotify.Event) {
cm.logger.Printf("配置文件变更: %s", e.Name)
if e.Op&fsnotify.Write == fsnotify.Write {
if err := cm.reloadConfig(); err != nil {
cm.logger.Errorf("重新加载配置失败: %v", err)
return
}
cm.logger.Info("配置重新加载成功")
}
},
}
}
// 重新加载配置
func (cm *ConfigManager) reloadConfig() error {
v := viper.GetViper()
// 重新读取配置
if err := v.ReadInConfig(); err != nil {
return fmt.Errorf("读取配置文件失败: %s", err.Error())
}
// 解析新配置
var newConfig Config
if err := v.Unmarshal(&newConfig); err != nil {
return fmt.Errorf("解析配置失败: %s", err.Error())
}
// 验证新配置
if err := cm.validateConfig(&newConfig); err != nil {
return fmt.Errorf("新配置验证失败: %s", err.Error())
}
// 比较配置变更
cm.mutex.Lock()
defer cm.mutex.Unlock()
changes := cm.compareConfig(cm.config, &newConfig)
// 应用新配置
oldConfig := cm.config
cm.config = &newConfig
// 通知配置监听器
for key, change := range changes {
if watchers, exists := cm.watchers[key]; exists {
for _, watcher := range watchers {
watcher.OnConfigChanged(key, change.OldValue, change.NewValue)
}
}
}
return nil
}
// 配置变更记录
type ConfigChange struct {
Key string `json:"key"`
OldValue interface{} `json:"old_value"`
NewValue interface{} `json:"new_value"`
Timestamp time.Time `json:"timestamp"`
}
// 比较配置变更
func (cm *ConfigManager) compareConfig(oldConfig, newConfig *Config) map[string]*ConfigChange {
changes := make(map[string]*ConfigChange)
// 使用反射比较结构体
oldValue := reflect.ValueOf(oldConfig).Elem()
newValue := reflect.ValueOf(newConfig).Elem()
cm.compareStruct(oldValue, newValue, "", changes)
return changes
}
// 递归比较结构体
func (cm *ConfigManager) compareStruct(oldValue, newValue reflect.Value, prefix string, changes map[string]*ConfigChange) {
structType := oldValue.Type()
for i := 0; i < oldValue.NumField(); i++ {
fieldName := structType.Field(i).Name
jsonTag := structType.Field(i).Tag.Get("mapstructure")
if jsonTag == "" {
jsonTag = strings.ToLower(fieldName)
}
fullKey := prefix + jsonTag
oldField := oldValue.Field(i)
newField := newValue.Field(i)
if oldField.Kind() == reflect.Struct {
cm.compareStruct(oldField, newField, fullKey+".", changes)
} else {
if !reflect.DeepEqual(oldField.Interface(), newField.Interface()) {
changes[fullKey] = &ConfigChange{
Key: fullKey,
OldValue: oldField.Interface(),
NewValue: newField.Interface(),
Timestamp: time.Now(),
}
}
}
}
}
// 注册配置监听器
func (cm *ConfigManager) Watch(key string, watcher ConfigWatcher) {
cm.mutex.Lock()
defer cm.mutex.Unlock()
if cm.watchers[key] == nil {
cm.watchers[key] = make([]ConfigWatcher, 0)
}
cm.watchers[key] = append(cm.watchers[key], watcher)
cm.logger.Infof("注册配置监听器: %s", key)
}
// 获取配置值
func (cm *ConfigManager) Get(key string) interface{} {
cm.mutex.RLock()
defer cm.mutex.RUnlock()
// 使用Viper获取配置值
return viper.Get(key)
}
// 获取字符串配置值
func (cm *ConfigManager) GetString(key string) string {
return cm.Get(key).(string)
}
// 获取整数配置值
func (cm *ConfigManager) GetInt(key string) int {
return cm.Get(key).(int)
}
// 获取布尔配置值
func (cm *ConfigManager) GetBool(key string) bool {
return cm.Get(key).(bool)
}
// 获取时长配置值
func (cm *ConfigManager) GetDuration(key string) time.Duration {
return cm.Get(key).(time.Duration)
}
// 设置配置值
func (cm *ConfigManager) Set(key string, value interface{}) error {
// 验证配置值
if rule, exists := cm.validationRules[key]; exists {
if err := rule.Validate(key, value); err != nil {
return fmt.Errorf("配置值验证失败: %s", err.Error())
}
}
cm.mutex.Lock()
defer cm.mutex.Unlock()
oldValue := viper.Get(key)
// 设置新值
viper.Set(key, value)
// 更新内存配置
cm.updateConfig(key, value)
// 通知监听器
if watchers, exists := cm.watchers[key]; exists {
for _, watcher := range watchers {
watcher.OnConfigChanged(key, oldValue, value)
}
}
cm.logger.Infof("配置更新: %s = %v", key, value)
return nil
}
// 更新配置结构体
func (cm *ConfigManager) updateConfig(key string, value interface{}) {
// 这里需要根据key更新对应的结构体字段
// 实现较为复杂，可以使用反射或专门的库
}
// 配置热更新使用示例
func ExampleConfigHotReload() {
logger := &ConsoleLogger{}
configManager, err := NewConfigManager("config.yaml", logger)
if err != nil {
log.Fatalf("创建配置管理器失败: %v", err)
}
// 注册配置监听器
configManager.Watch("server.http.addr", &DatabaseConfigWatcher{})
configManager.Watch("log.level", &LogLevelWatcher{})
// 运行应用
runApp(configManager)
}
// 数据库配置监听器
type DatabaseConfigWatcher struct{}
func (w *DatabaseConfigWatcher) OnConfigChanged(key string, oldValue, newValue interface{}) {
log.Printf("数据库配置变更: %s = %v", key, newValue)
// 重新初始化数据库连接
if err := reinitializeDatabase(); err != nil {
log.Printf("重新初始化数据库连接失败: %v", err)
}
}
// 日志级别监听器
type LogLevelWatcher struct{}
func (w *LogLevelWatcher) OnConfigChanged(key string, oldValue, newValue interface{}) {
log.Printf("日志级别变更: %s = %v", key, newValue)
// 更新日志级别
if level, ok := newValue.(string); ok {
updateLogLevel(level)
}
}
---
1.8 版本历史
01.Kratos框架发展历程
a.起源背景
a.设计初衷
Kratos最初是为了解决企业级微服务开发中的痛点而创建，旨在提供一套完整、高效、易用的微服务开发框架。
b.技术选型
基于Go语言的并发优势和云原生生态，结合业界最佳实践，打造面向未来的微服务框架。
c.开源历程
从内部工具到开源框架，经历了多轮迭代和社区反馈，逐步发展成熟。
d.发展里程碑示例
---
// Kratos发展历程时间线示例
package history
// 重要版本里程碑
type Milestone struct {
Version string `json:"version"`
ReleaseDate time.Time `json:"release_date"`
Title string `json:"title"`
Description string `json:"description"`
Features []string `json:"features"`
Breaking []string `json:"breaking_changes"`
Impact string `json:"impact"`
}
var kratosMilestones = []Milestone{
{
Version: "v0.1.0",
ReleaseDate: time.Date(2019, 3, 15, 0, 0, 0, 0, time.UTC),
Title: "初始发布",
Description: "Kratos首个版本发布，提供基础的微服务开发能力",
Features: []string{
"基础应用生命周期管理",
"HTTP/gRPC服务支持",
"简单的配置管理",
"基础日志记录",
},
Impact: "标志着Kratos框架的诞生，为企业微服务开发提供了新的选择",
},
{
Version: "v0.3.0",
ReleaseDate: time.Date(2019, 8, 20, 0, 0, 0, 0, time.UTC),
Title: "中间件系统",
Description: "引入了完整的中间件系统，增强了框架的可扩展性",
Features: []string{
"HTTP和gRPC中间件支持",
"内置认证和授权中间件",
"日志和监控中间件",
"自定义中间件支持",
},
Breaking: []string{
"中间件接口发生变更",
"配置文件格式调整",
},
Impact: "大幅提升了框架的可扩展性和可定制性",
},
{
Version: "v1.0.0",
ReleaseDate: time.Date(2020, 2, 1, 0, 0, 0, 0, time.UTC),
Title: "稳定版本",
Description: "首个稳定版本发布，API接口趋于稳定，适合生产环境使用",
Features: []string{
"完整的微服务工具链",
"服务注册发现",
"配置热更新",
"链路追踪集成",
"Prometheus监控",
},
Impact: "标志着Kratos框架的成熟，开始在生产环境中大规模应用",
},
{
Version: "v2.0.0",
ReleaseDate: time.Date(2021, 1, 15, 0, 0, 0, 0, time.UTC),
Title: "架构重构",
Description: "重大架构升级，采用Clean Architecture设计理念",
Features: []string{
"Clean Architecture分层设计",
"DDD支持增强",
"更好的依赖注入",
"模块化架构",
"性能优化",
},
Breaking: []string{
"项目结构重大变更",
"API接口重新设计",
"配置格式更新",
"依赖注入方式变更",
},
Impact: "为大规模企业应用提供了更好的架构支撑",
},
{
Version: "v2.3.0",
ReleaseDate: time.Date(2021, 9, 10, 0, 0, 0, 0, time.UTC),
Title: "云原生增强",
Description: "增强云原生特性，深度集成Kubernetes生态",
Features: []string{
"Kubernetes集成增强",
"健康检查完善",
"优雅关闭支持",
"多环境配置支持",
"服务网格兼容性",
},
Impact: "使Kratos更好地适应云原生部署环境",
},
{
Version: "v2.6.0",
ReleaseDate: time.Date(2022, 4, 5, 0, 0, 0, 0, time.UTC),
Title: "可观测性完善",
Description: "完整的可观测性支持，集成OpenTelemetry标准",
Features: []string{
"OpenTelemetry集成",
"分布式链路追踪",
"结构化日志",
"自定义指标支持",
"告警规则支持",
},
Impact: "为微服务运维提供了强大的可观测性能力",
},
}
// 版本特性对比
func CompareVersions(v1, v2 string) (*VersionComparison, error) {
version1, err := parseVersion(v1)
if err != nil {
return nil, fmt.Errorf("解析版本 %s 失败: %s", v1, err.Error())
}
version2, err := parseVersion(v2)
if err != nil {
return nil, fmt.Errorf("解析版本 %s 失败: %s", v2, err.Error())
}
return &VersionComparison{
Version1: version1,
Version2: version2,
Compatibility: checkCompatibility(version1, version2),
UpgradePath: getUpgradePath(version1, version2),
BreakingChanges: getBreakingChanges(version1, version2),
NewFeatures: getNewFeatures(version1, version2),
}, nil
}
type VersionComparison struct {
Version1 *Version `json:"version1"`
Version2 *Version `json:"version2"`
Compatibility CompatibilityLevel `json:"compatibility"`
UpgradePath []string `json:"upgrade_path"`
BreakingChanges []string `json:"breaking_changes"`
NewFeatures []string `json:"new_features"`
}
type CompatibilityLevel int
const (
CompatibilityFull CompatibilityLevel = iota
CompatibilityPartial
CompatibilityBreaking
)
// 版本升级指导
func GenerateUpgradeGuide(fromVersion, toVersion string) (*UpgradeGuide, error) {
comparison, err := CompareVersions(fromVersion, toVersion)
if err != nil {
return nil, err
}
guide := &UpgradeGuide{
FromVersion: fromVersion,
ToVersion: toVersion,
Difficulty: calculateUpgradeDifficulty(comparison),
EstimatedTime: estimateUpgradeTime(comparison),
Steps: generateUpgradeSteps(comparison),
Checklist: generateChecklist(comparison),
RollbackPlan: generateRollbackPlan(fromVersion, toVersion),
TestingStrategy: generateTestingStrategy(comparison),
}
return guide, nil
}
type UpgradeGuide struct {
FromVersion string `json:"from_version"`
ToVersion string `json:"to_version"`
Difficulty string `json:"difficulty"`
EstimatedTime time.Duration `json:"estimated_time"`
Steps []UpgradeStep `json:"steps"`
Checklist []ChecklistItem `json:"checklist"`
RollbackPlan RollbackPlan `json:"rollback_plan"`
TestingStrategy TestingStrategy `json:"testing_strategy"`
}
type UpgradeStep struct {
Order int `json:"order"`
Title string `json:"title"`
Description string `json:"description"`
Commands []string `json:"commands"`
Validation string `json:"validation"`
}
// 生成升级步骤
func generateUpgradeSteps(comparison *VersionComparison) []UpgradeStep {
var steps []UpgradeStep
if comparison.Compatibility == CompatibilityBreaking {
steps = append(steps, UpgradeStep{
Order: 1,
Title: "代码备份",
Description: "创建当前代码的完整备份",
Commands: []string{
"git checkout -b backup-before-upgrade",
"git add .",
"git commit -m \"Backup before Kratos upgrade\"",
},
Validation: "确保备份已创建",
})
}
steps = append(steps, UpgradeStep{
Order: 2,
Title: "依赖更新",
Description: "更新Kratos相关依赖到目标版本",
Commands: []string{
"go get -u github.com/go-kratos/kratos/v2@" + comparison.Version2.String(),
"go mod tidy",
},
Validation: "检查go.mod文件中的版本是否正确",
})
if len(comparison.BreakingChanges) > 0 {
steps = append(steps, UpgradeStep{
Order: 3,
Title: "代码迁移",
Description: "根据破坏性变更更新代码",
Commands: []string{},
Validation: "确保所有破坏性变更都已处理",
})
}
steps = append(steps, UpgradeStep{
Order: 4,
Title: "配置更新",
Description: "更新配置文件格式",
Commands: []string{},
Validation: "验证配置文件格式正确",
})
steps = append(steps, UpgradeStep{
Order: 5,
Title: "测试验证",
Description: "运行完整测试套件",
Commands: []string{
"go test ./...",
"go build ./...",
},
Validation: "所有测试通过，编译成功",
})
return steps
}
---
02.主要版本特性演进
a.v1.x系列 - 基础稳定期
a.v1.0.0 (2020-02-01)
- 首个稳定版本发布
- 完整的微服务开发工具链
- 服务注册发现机制
- 配置管理和热更新
- HTTP/gRPC协议支持
b.v1.2.0 (2020-06-15)
- 添加中间件系统
- 增强日志记录能力
- 支持多种序列化格式
- 性能优化和bug修复
c.v1.5.0 (2020-11-20)
- 集成Prometheus监控
- 支持分布式链路追踪
- 完善错误处理机制
- 添加更多数据源支持
b.v2.x系列 - 架构重构期
a.v2.0.0 (2021-01-15)
- 重大架构重构，采用Clean Architecture
- DDD设计模式支持
- 模块化架构设计
- 性能大幅提升
- API接口重新设计
b.v2.3.0 (2021-09-10)
- 云原生特性增强
- Kubernetes深度集成
- 优雅关闭和健康检查
- 多环境配置支持
- 服务网格兼容性
c.v2.6.0 (2022-04-05)
- OpenTelemetry集成
- 完整的可观测性支持
- 自定义指标和告警
- 结构化日志增强
- 性能监控仪表板
03.社区发展历程
a.开源生态建设
a.GitHub社区成长
从最初的几十个star到现在的数万个star，社区活跃度持续提升。
b.贡献者网络
全球范围内的开发者参与贡献，形成了活跃的开源社区。
c.企业采用情况
被众多企业用于生产环境，形成了丰富的最佳实践。
d.社区贡献示例
---
// 社区贡献统计示例
package community
type ContributionStats struct {
Contributors int `json:"contributors"`
Commits int `json:"commits"`
PullRequests int `json:"pull_requests"`
Issues int `json:"issues"`
Stars int `json:"stars"`
Forks int `json:"forks"`
Releases int `json:"releases"`
Companies []Company `json:"companies"`
TopContributors []Contributor `json:"top_contributors"`
}
type Company struct {
Name string `json:"name"`
Website string `json:"website"`
Country string `json:"country"`
Usage string `json:"usage"`
}
type Contributor struct {
Username string `json:"username"`
Commits int `json:"commits"`
PullReq int `json:"pull_requests"`
Issues int `json:"issues"`
Country string `json:"country"`
}
// 模拟社区统计数据
var communityStats = ContributionStats{
Contributors: 500,
Commits: 3000,
PullRequests: 1200,
Issues: 800,
Stars: 15000,
Forks: 3000,
Releases: 25,
Companies: []Company{
{
Name: "阿里巴巴",
Website: "https://www.alibaba.com",
Country: "中国",
Usage: "电商平台的微服务基础设施",
},
{
Name: "字节跳动",
Website: "https://www.bytedance.com",
Country: "中国",
Usage: "内容推荐系统的微服务架构",
},
{
Name: "美团",
Website: "https://www.meituan.com",
Country: "中国",
Usage: "外卖平台的订单处理系统",
},
{
Name: "腾讯",
Website: "https://www.tencent.com",
Country: "中国",
Usage: "游戏服务器的微服务化改造",
},
{
Name: "Bilibili",
Website: "https://www.bilibili.com",
Country: "中国",
Usage: "视频处理和推荐系统",
},
},
TopContributors: []Contributor{
{
Username: "go-kratos-team",
Commits: 150,
PullReq: 50,
Issues: 30,
Country: "中国",
},
},
}
// 社区活动记录
type CommunityEvent struct {
Date time.Time `json:"date"`
Title string `json:"title"`
Description string `json:"description"`
Location string `json:"location"`
Participants int `json:"participants"`
Type string `json:"type"`
}
var communityEvents = []CommunityEvent{
{
Date: time.Date(2021, 6, 15, 0, 0, 0, 0, time.UTC),
Title: "Kratos v2.0 发布派对",
Description: "庆祝Kratos v2.0版本发布，分享新特性",
Location: "北京",
Participants: 100,
Type: "Meetup",
},
{
Date: time.Date(2022, 3, 20, 0, 0, 0, 0, time.UTC),
Title: "Kratos云原生实践分享",
Description: "分享Kratos在云原生环境中的最佳实践",
Location: "上海",
Participants: 150,
Type: "Conference",
},
{
Date: time.Date(2022, 9, 10, 0, 0, 0, 0, time.UTC),
Title: "Kratos Contributors Summit",
Description: "年度贡献者峰会，讨论未来发展方向",
Location: "深圳",
Participants: 50,
Type: "Summit",
},
}
// 开源项目影响力
func calculateInfluence(stats ContributionStats) InfluenceMetrics {
return InfluenceMetrics{
CodeQuality: float64(stats.PullRequests) / float64(stats.Commits) * 100,
CommunityHealth: float64(stats.Contributors) / float64(stats.Stars) * 100,
AdoptionRate: float64(stats.Forks) / float64(stats.Stars) * 100,
Maintenance: float64(stats.Commits) / float64(stats.Issues) * 100,
OverallScore: calculateOverallScore(stats),
}
}
type InfluenceMetrics struct {
CodeQuality float64 `json:"code_quality"`
CommunityHealth float64 `json:"community_health"`
AdoptionRate float64 `json:"adoption_rate"`
Maintenance float64 `json:"maintenance"`
OverallScore float64 `json:"overall_score"`
}
func calculateOverallScore(stats ContributionStats) float64 {
quality := float64(stats.PullRequests) / float64(stats.Commits)
health := float64(stats.Contributors) / float64(stats.Stars)
adoption := float64(stats.Forks) / float64(stats.Stars)
maintenance := float64(stats.Commits) / float64(stats.Issues)
return (quality + health + adoption + maintenance) / 4 * 100
}
---
04.技术债务演进
a.架构重构记录
a.v1.x到v2.x重构
- 从单体架构向分层架构演进
- 引入DDD和Clean Architecture
- API接口重新设计
- 性能优化和内存使用改进
b.代码质量提升
- 持续的代码审查和重构
- 测试覆盖率提升
- 文档完善和示例增加
- 性能基准测试建立
b.性能优化历程
a.内存管理优化
- 对象池机制引入
- 内存泄漏修复
- GC压力减少
- 内存使用监控
b.网络性能优化
- 连接池优化
- 序列化性能提升
- 压缩算法集成
- 网络IO优化
c.并发性能优化
- 协程池管理
- 锁竞争减少
- 无锁数据结构
- 并发安全改进
05.未来发展规划
a.技术演进方向
a.云原生深化
- Service Mesh深度集成
- Serverless架构支持
- 事件驱动架构
- 多云部署支持
b.开发体验提升
a.AI辅助开发
- 代码生成工具增强
- 智能配置推荐
- 自动化测试生成
- 性能优化建议
b.开发者工具
- 可视化配置工具
- 调试工具增强
- 性能分析器
- 文档生成器
c.生态系统扩展
a.插件市场
- 官方插件市场建设
- 第三方插件支持
- 插件开发工具链
- 插件质量认证
b.多语言支持
- Go版本兼容性
- 其他语言桥接
- 互操作性标准
- 跨语言调试
d.版本发布计划
a.v3.0.0路线图
- 预计2024年发布
- 全新的架构设计
- 更多AI特性集成
- 更好的开发者体验
b.长期愿景
- 成为Go生态中最受欢迎的微服务框架
- 建立完整的开发者生态系统
- 推动微服务最佳实践的普及
- 为云原生应用提供标准化的解决方案
06.版本升级指南
a.升级策略建议
a.渐进式升级
- 建议逐个小版本升级，避免跨越式升级
- 在测试环境充分验证后再升级生产环境
- 保留完整的回滚方案
b.兼容性考虑
- 关注API变更和配置格式变化
- 测试现有功能的兼容性
- 准备数据迁移方案
c.团队培训
- 组织团队培训，了解新特性
- 更新开发规范和最佳实践
- 建立问题反馈机制
b.升级流程示例
a.升级前准备
- 代码备份和版本控制
- 环境准备和依赖检查
- 测试数据和用例准备
- 回滚方案制定
b.升级执行
- 依赖更新和代码迁移
- 配置文件调整
- 数据迁移执行
- 功能测试验证
c.升级后验证
- 性能测试对比
- 功能完整性验证
- 监控指标检查
- 用户反馈收集
2 核心组件
2.1 汇总：9个核心组件
01.传输层组件(Transport)
a.功能概述
提供HTTP和gRPC两种通信协议支持，处理客户端请求和服务间通信，是微服务与外部世界交互的桥梁。
b.核心特性
a.协议支持
支持HTTP/1.1、HTTP/2和gRPC协议，满足不同场景的通信需求。
b.中间件机制
提供丰富的中间件支持，包括认证、授权、限流、熔断等功能。
c.性能优化
连接复用、压缩传输、流式处理等性能优化特性。
d.错误处理
统一的错误处理机制，支持错误传播和转换。
d.使用场景
a.Web应用接入
处理浏览器和移动应用的HTTP请求。
b.微服务间通信
使用gRPC进行高效的内部服务调用。
c.API网关集成
与API网关配合，提供统一的接入点。
02.应用生命周期组件(Application)
a.功能概述
管理微服务的完整生命周期，包括启动、运行、健康检查和优雅关闭等阶段。
b.核心特性
a.生命周期管理
标准化的启动、运行和关闭流程管理。
b.依赖注入
自动化的依赖管理和对象生命周期控制。
c.健康检查
内置健康检查机制，支持多维度状态监控。
d.信号处理
优雅处理系统信号，确保安全关闭。
c.使用场景
a.微服务启动
标准化的服务启动流程。
b.服务部署
与容器编排系统的集成。
c.服务监控
提供服务状态信息给监控系统。
03.配置管理组件(Config)
a.功能概述
提供统一的配置管理能力，支持多种数据源和动态更新机制。
b.核心特性
a.多源支持
支持文件、环境变量、命令行参数、配置中心等多种数据源。
b.热更新
运行时动态更新配置，无需重启服务。
c.类型安全
强类型的配置解析和验证。
d.分层配置
支持多环境、多分层的配置管理。
c.使用场景
a.环境配置
开发、测试、生产环境的配置管理。
b.特性开关
动态控制功能特性的开启和关闭。
c.敏感信息
安全的密钥和凭证管理。
04.日志系统组件(Logging)
a.功能概述
提供结构化日志记录能力，支持多种输出格式和日志级别控制。
b.核心特性
a.结构化日志
使用键值对格式记录日志，便于机器解析和查询分析。
b.多输出目标
支持文件、控制台、远程日志服务等多种输出目标。
c.日志级别
支持DEBUG、INFO、WARN、ERROR、FATAL等多个日志级别。
d.上下文传递
在请求链路中传递上下文信息，实现日志的关联查询。
c.使用场景
a.问题排查
详细记录系统运行状态，便于问题定位。
b.审计追踪
记录关键业务操作，满足合规要求。
c.性能分析
通过日志分析系统性能瓶颈。
05.监控系统组件(Metrics)
a.功能概述
集成Prometheus监控指标，提供丰富的性能指标采集和监控能力。
b.核心特性
a.标准指标
提供HTTP、gRPC、业务等标准化的性能指标。
b.自定义指标
支持业务相关的自定义指标定义和采集。
c.指标导出
兼容Prometheus格式的指标导出。
d.性能分析
内置的性能分析和统计功能。
c.使用场景
a.系统监控
实时监控系统运行状态和性能指标。
b.告警通知
基于指标阈值设置告警规则。
c.容量规划
通过指标分析进行容量规划和优化。
06.链路追踪组件(Tracing)
a.功能概述
基于OpenTelemetry标准，实现分布式系统的请求链路追踪。
b.核心特性
a.分布式追踪
跨多个服务的完整请求链路追踪。
b.性能分析
分析各环节的性能瓶颈和延迟分布。
c.错误定位
快速定位分布式系统中的错误和异常。
d.可视化
提供链路可视化界面和报告。
c.使用场景
a.性能调优
通过链路分析识别性能瓶颈。
b.故障排查
快速定位跨服务调用中的问题。
c.服务依赖分析
分析服务间的依赖关系和调用模式。
07.服务注册发现组件(Registry)
a.功能概述
提供服务的自动注册和发现机制，支持动态的服务拓扑管理。
b.核心特性
a.服务注册
自动注册服务实例信息到注册中心。
b.服务发现
动态发现和获取可用服务实例列表。
c.健康检查
定期检查服务实例的健康状态。
d.负载均衡
支持多种负载均衡策略。
c.使用场景
a.微服务架构
动态管理大规模微服务集群。
b.服务治理
实现服务的自动发现和故障转移。
c.弹性扩缩容
支持服务的动态扩容和缩容。
08.中间件系统组件(Middleware)
a.功能概述
提供可插拔的中间件系统，支持横切关注点的统一处理。
b.核心特性
a.链式处理
支持多个中间件的链式组合和处理。
b.拦截器模式
统一的请求拦截和处理机制。
c.可扩展性
支持自定义中间件的开发和注册。
d.预置中间件
提供丰富的预置中间件，如认证、限流、熔断等。
c.使用场景
a.安全控制
统一的认证和授权处理。
b.流量控制
限流、熔断、重试等流量控制机制。
c.监控日志
统一的请求监控和日志记录。
09.服务发现组件(Discovery)
a.功能概述
提供服务发现和负载均衡功能，支持多种发现策略和健康检查机制。
b.核心特性
a.多种发现机制
支持Consul、Etcd、Nacos等服务发现中心。
b.负载均衡
支持轮询、随机、加权等多种负载均衡策略。
c.健康检查
多维度的健康检查和故障检测。
d.故障转移
自动故障转移和服务恢复机制。
c.使用场景
a.微服务通信
动态发现服务实例进行通信。
b.服务治理
实现服务的健康管理和故障处理。
c.多环境部署
支持不同环境的服务发现策略。
10.组件交互关系
a.Application作为核心
Application是所有组件的协调中心，负责统一管理和调度。
b.Transport作为入口
Transport是外部请求的入口点，与中间件系统紧密配合。
c.Config作为基础
Config为所有组件提供配置支持，支持热更新机制。
d.Logging/Metrics/Tracing作为支撑
这三个组件为整个系统提供可观测性支撑。
e.Registry/Discovery作为治理基础
为服务间的通信和治理提供基础支撑。
11.组件架构示例
---
// Kratos组件架构示例
package architecture
import (
"context"
"time"
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/registry"
"github.com/go-kratos/kratos/v2/transport"
)
// 组件集成示例
func NewApp() *kratos.App {
// 1. 配置组件初始化
c := config.New(
config.WithSource(file.NewSource("configs/config.yaml")),
)
c.Load()
// 2. 日志组件初始化
logger := log.NewStdLogger(os.Stdout,
log.WithLevel(log.LevelInfo),
log.WithContext(log.WithCaller()),
)
// 3. 注册中心初始化
r := consul.NewRegistry(consul.WithAddress("localhost:8500"))
// 4. HTTP传输层组件
httpServer := http.NewServer(
http.Address(":8080"),
http.Middleware(
recovery.Recovery(),
logging.Server(logger),
metrics.Server(),
tracing.Server(),
),
)
// 5. gRPC传输层组件
grpcServer := grpc.NewServer(
grpc.Address(":9090"),
grpc.Middleware(
recovery.Recovery(),
logging.Server(logger),
metrics.Server(),
tracing.Server(),
),
)
// 6. 应用组件集成
app := kratos.New(
kratos.Name("demo-service"),
kratos.Version("v1.0.0"),
kratos.Metadata(map[string]string{}),
kratos.Logger(logger),
kratos.Server(
httpServer,
grpcServer,
),
kratos.Registrar(r), // 服务注册组件
)
return app
}
// 组件协同工作示例
func ComponentCollaborationExample() {
// 配置热更新示例
config.Watch("database.max_connections", func(key string, value interface{}) {
logger.Infof("配置变更: %s = %v", key, value)
// 通知数据库连接池更新
updateDatabasePool(value.(int))
})
// 健康检查组件集成
app := kratos.New(
kratos.Name("health-check-demo"),
kratos.Registrar(registry),
kratos.Server(
http.NewServer(
http.Address(":8080"),
// 健康检查中间件
http.Middleware(
healthCheckMiddleware(),
),
),
),
)
// 优雅关闭处理
app.BeforeStop(func(ctx context.Context) error {
logger.Info("开始优雅关闭...")
// 停止接受新请求
// 等待现有请求完成
// 清理资源
logger.Info("优雅关闭完成")
return nil
})
}
// 健康检查中间件
func healthCheckMiddleware() http.Middleware {
return func(handler http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path == "/health" {
// 执行健康检查
health := performHealthCheck()
if health.Status == "healthy" {
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(health)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
json.NewEncoder(w).Encode(health)
}
return
}
handler.ServeHTTP(w, r)
})
}
}
// 健康检查结果
func performHealthCheck() HealthCheckResult {
result := HealthCheckResult{
Status: "healthy",
Timestamp: time.Now(),
Checks: make(map[string]CheckResult),
}
// 检查数据库连接
if err := checkDatabase(); err != nil {
result.Status = "unhealthy"
result.Checks["database"] = CheckResult{
Status: "unhealthy",
Error: err.Error(),
}
} else {
result.Checks["database"] = CheckResult{
Status: "healthy",
}
}
// 检查Redis连接
if err := checkRedis(); err != nil {
result.Status = "unhealthy"
result.Checks["redis"] = CheckResult{
Status: "unhealthy",
Error: err.Error(),
}
} else {
result.Checks["redis"] = CheckResult{
Status: "healthy",
}
}
return result
}
type HealthCheckResult struct {
Status string `json:"status"`
Timestamp time.Time `json:"timestamp"`
Checks map[string]CheckResult `json:"checks"`
}
type CheckResult struct {
Status string `json:"status"`
Error string `json:"error,omitempty"`
}
// 组件生命周期管理示例
func LifecycleManagementExample() {
app := kratos.New(
kratos.Name("lifecycle-demo"),
// 启动前回调
kratos.BeforeStart(func(ctx context.Context) error {
logger.Info("应用启动前准备...")
// 初始化数据库连接
// 缓存预热
// 服务注册
return nil
}),
// 启动后回调
kratos.AfterStart(func(ctx context.Context) error {
logger.Info("应用启动完成...")
// 启动后台任务
// 定时任务注册
return nil
}),
// 停止前回调
kratos.BeforeStop(func(ctx context.Context) error {
logger.Info("应用停止前清理...")
// 停止接受新请求
// 完成正在处理的请求
return nil
}),
// 停止后回调
kratos.AfterStop(func(ctx context.Context) error {
logger.Info("应用停止完成...")
// 资源清理
// 服务注销
return nil
}),
)
// 启动应用
if err := app.Run(); err != nil {
logger.Errorf("应用启动失败: %v", err)
}
}
---
2.2 服务传输层 Transport
01.Transport层架构设计
a.分层架构
a.协议层
负责HTTP和gRPC协议的具体实现，处理协议相关的细节。
b.中间件层
提供可插拔的中间件支持，实现横切关注点的处理。
c.路由层
负责请求路由和方法分发，将请求映射到具体的处理器。
d.编解码层
负责数据的序列化和反序列化，支持多种数据格式。
b.接口抽象
a.Server接口
定义服务器的基本操作，包括启动、停止、优雅关闭等。
b.Transport接口
定义传输层的基本特性，包括协议支持、连接管理等。
c.Endpoint接口
定义服务端点的抽象，支持多种协议的统一处理。
c.Transport架构示例
---
// Transport层架构示例
package transport
import (
"context"
"net"
"time"
"github.com/go-kratos/kratos/v2/transport"
)
// 传输层接口定义
type Transport interface {
// 启动传输层
Start(ctx context.Context) error
// 停止传输层
Stop(ctx context.Context) error
// 获取端点信息
Endpoint() string
// 获取监听地址
Address() string
}
// 服务器接口定义
type Server interface {
// 注册服务
Register(svc interface{}) error
// 启动服务器
Start(ctx context.Context) error
// 停止服务器
Stop(ctx context.Context) error
// 获取服务器信息
Info() *ServerInfo
}
// 服务器信息
type ServerInfo struct {
Name string `json:"name"`
Version string `json:"version"`
Metadata map[string]string `json:"metadata"`
Endpoints []string `json:"endpoints"`
}
// 端点抽象
type Endpoint struct {
Scheme string `json:"scheme"`
Host string `json:"host"`
Port int `json:"port"`
Path string `json:"path"`
Metadata map[string]string `json:"metadata"`
}
func (e Endpoint) String() string {
return fmt.Sprintf("%s://%s:%d%s", e.Scheme, e.Host, e.Port, e.Path)
}
// 中间件接口
type Middleware func(Handler) Handler
// 处理器接口
type Handler interface {
ServeHTTP(ctx context.Context, req interface{}) (interface{}, error)
ServeGRPC(ctx context.Context, req interface{}) (interface{}, error)
}
// 传输层基础实现
type BaseTransport struct {
endpoint Endpoint
middleware []Middleware
listeners []net.Listener
ctx context.Context
cancel context.CancelFunc
}
func NewBaseTransport(endpoint Endpoint, middleware ...Middleware) *BaseTransport {
ctx, cancel := context.WithCancel(context.Background())
return &BaseTransport{
endpoint: endpoint,
middleware: middleware,
ctx: ctx,
cancel: cancel,
}
}
func (t *BaseTransport) Endpoint() string {
return t.endpoint.String()
}
func (t *BaseTransport) Address() string {
return fmt.Sprintf("%s:%d", t.endpoint.Host, t.endpoint.Port)
}
func (t *BaseTransport) AddListener(listener net.Listener) {
t.listeners = append(t.listeners, listener)
}
func (t *BaseTransport) Stop(ctx context.Context) error {
t.cancel()
for _, listener := range t.listeners {
if err := listener.Close(); err != nil {
return fmt.Errorf("关闭监听器失败: %s", err.Error())
}
}
return nil
}
---
02.HTTP传输层实现
a.特性概述
a.协议支持
完整支持HTTP/1.1和HTTP/2协议，包括Keep-Alive、分块传输等特性。
b.路由系统
基于路由器的请求路由机制，支持路径参数、查询参数等多种路由方式。
c.中间件集成
与Kratos中间件系统深度集成，支持链式中间件处理。
d.性能优化
连接池管理、压缩传输、静态文件服务等性能优化特性。
b.HTTP服务器配置
a.基础配置
包括监听地址、超时设置、最大连接数等基础参数配置。
b.TLS配置
支持HTTPS协议，包括证书配置、安全策略等。
c.性能调优
连接超时、读写缓冲区、Keep-Alive等性能相关配置。
d.HTTP服务器示例
---
// HTTP传输层实现示例
package http
import (
"context"
"crypto/tls"
"net"
"net/http"
"time"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/gorilla/mux"
)
// HTTP服务器配置
type ServerConfig struct {
Address string `json:"address"`
Timeout time.Duration `json:"timeout"`
ReadTimeout time.Duration `json:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout"`
IdleTimeout time.Duration `json:"idle_timeout"`
MaxHeaderBytes int `json:"max_header_bytes"`
TLS *TLSConfig `json:"tls,omitempty"`
Middleware []string `json:"middleware"`
}
type TLSConfig struct {
CertFile string `json:"cert_file"`
KeyFile string `json:"key_file"`
ClientAuth bool `json:"client_auth"`
}
// HTTP服务器实现
type HTTPServer struct {
config *ServerConfig
router *mux.Router
server *http.Server
listeners []net.Listener
middleware []http.Middleware
ctx context.Context
cancel context.CancelFunc
}
// 创建HTTP服务器
func NewHTTPServer(config *ServerConfig, middleware ...http.Middleware) *HTTPServer {
ctx, cancel := context.WithCancel(context.Background())
server := &HTTPServer{
config: config,
router: mux.NewRouter(),
middleware: middleware,
ctx: ctx,
cancel: cancel,
}
server.setupServer()
server.setupRoutes()
return server
}
// 设置HTTP服务器
func (s *HTTPServer) setupServer() {
s.server = &http.Server{
Addr: s.config.Address,
Handler: s.router,
ReadTimeout: s.config.ReadTimeout,
WriteTimeout: s.config.WriteTimeout,
IdleTimeout: s.config.IdleTimeout,
MaxHeaderBytes: s.config.MaxHeaderBytes,
}
// 配置TLS
if s.config.TLS != nil {
s.setupTLS()
}
// 设置连接状态回调
s.server.ConnState = s.onConnStateChange
}
// 配置TLS
func (s *HTTPServer) setupTLS() {
cert, err := tls.LoadX509KeyPair(s.config.TLS.CertFile, s.config.TLS.KeyFile)
if err != nil {
panic(fmt.Sprintf("加载TLS证书失败: %s", err.Error()))
}
s.server.TLSConfig = &tls.Config{
Certificates: []tls.Certificate{cert},
MinVersion: tls.VersionTLS12,
CipherSuites: []uint16{
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
tls.TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,
},
}
if s.config.TLS.ClientAuth {
s.server.TLSConfig.ClientAuth = tls.RequireAndVerifyClientCert
}
}
// 连接状态变更处理
func (s *HTTPServer) onConnStateChange(conn net.Conn, state http.ConnState) {
switch state {
case http.StateNew:
log.Printf("新HTTP连接: %s", conn.RemoteAddr())
case http.StateActive:
log.Printf("HTTP连接激活: %s", conn.RemoteAddr())
case http.StateIdle:
log.Printf("HTTP连接空闲: %s", conn.RemoteAddr())
case http.StateClosed:
log.Printf("HTTP连接关闭: %s", conn.RemoteAddr())
case http.StateHijacked:
log.Printf("HTTP连接被劫持: %s", conn.RemoteAddr())
}
}
// 设置路由
func (s *HTTPServer) setupRoutes() {
// 健康检查端点
s.router.HandleFunc("/health", s.healthCheckHandler).Methods("GET")
s.router.HandleFunc("/ready", s.readinessCheckHandler).Methods("GET")
s.router.HandleFunc("/metrics", s.metricsHandler).Methods("GET")
// API版本分组
v1 := s.router.PathPrefix("/api/v1").Subrouter()
v1.Use(s.corsMiddleware)
v1.Use(s.loggingMiddleware)
v1.Use(s.authMiddleware)
// 业务路由
s.setupBusinessRoutes(v1)
}
// 设置业务路由
func (s *HTTPServer) setupBusinessRoutes(router *mux.Router) {
// 用户管理路由
users := router.PathPrefix("/users").Subrouter()
users.HandleFunc("", s.createUserHandler).Methods("POST")
users.HandleFunc("/{id}", s.getUserHandler).Methods("GET")
users.HandleFunc("/{id}", s.updateUserHandler).Methods("PUT")
users.HandleFunc("/{id}", s.deleteUserHandler).Methods("DELETE")
// 订单管理路由
orders := router.PathPrefix("/orders").Subrouter()
orders.HandleFunc("", s.createOrderHandler).Methods("POST")
orders.HandleFunc("/{id}", s.getOrderHandler).Methods("GET")
orders.HandleFunc("/{id}", s.updateOrderHandler).Methods("PUT")
orders.HandleFunc("/{id}/cancel", s.cancelOrderHandler).Methods("POST")
// 文件上传路由
router.HandleFunc("/upload", s.uploadFileHandler).Methods("POST")
router.HandleFunc("/files/{filename}", s.serveFileHandler).Methods("GET")
}
// 启动HTTP服务器
func (s *HTTPServer) Start(ctx context.Context) error {
// 创建监听器
listener, err := net.Listen("tcp", s.config.Address)
if err != nil {
return fmt.Errorf("创建监听器失败: %s", err.Error())
}
s.listeners = append(s.listeners, listener)
log.Printf("HTTP服务器启动在: %s", s.config.Address)
// 启动服务器
go func() {
<-ctx.Done()
log.Printf("正在停止HTTP服务器...")
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
s.server.Shutdown(ctx)
}()
if s.config.TLS != nil {
return s.server.ServeTLS(listener, s.config.TLS.CertFile, s.config.TLS.KeyFile)
} else {
return s.server.Serve(listener)
}
}
// 停止HTTP服务器
func (s *HTTPServer) Stop(ctx context.Context) error {
s.cancel()
return s.server.Shutdown(ctx)
}
// 健康检查处理器
func (s *HTTPServer) healthCheckHandler(w http.ResponseWriter, r *http.Request) {
health := s.performHealthCheck()
w.Header().Set("Content-Type", "application/json")
if health.Status == "healthy" {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(health)
}
// 就绪检查处理器
func (s *HTTPServer) readinessCheckHandler(w http.ResponseWriter, r *http.Request) {
ready := s.performReadinessCheck()
w.Header().Set("Content-Type", "application/json")
if ready {
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"status": "ready"}`))
} else {
w.WriteHeader(http.StatusServiceUnavailable)
w.Write([]byte(`{"status": "not ready"}`))
}
}
// 指标处理器
func (s *HTTPServer) metricsHandler(w http.ResponseWriter, r *http.Request) {
// 返回Prometheus格式的指标
metrics := s.collectMetrics()
w.Header().Set("Content-Type", "text/plain")
w.Write([]byte(metrics))
}
// CORS中间件
func (s *HTTPServer) corsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
}
// 日志中间件
func (s *HTTPServer) loggingMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
// 创建响应记录器
recorder := &responseRecorder{
ResponseWriter: w,
statusCode: http.StatusOK,
}
// 处理请求
next.ServeHTTP(recorder, r)
// 记录请求日志
duration := time.Since(start)
log.Printf("%s %s %d %v %s",
r.Method,
r.URL.Path,
recorder.statusCode,
duration,
r.UserAgent(),
)
// 记录指标
s.recordMetrics(r.Method, r.URL.Path, recorder.statusCode, duration)
})
}
// 认证中间件
func (s *HTTPServer) authMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
authHeader := r.Header.Get("Authorization")
if authHeader == "" {
http.Error(w, "未授权", http.StatusUnauthorized)
return
}
// 验证令牌
if !s.validateToken(authHeader) {
http.Error(w, "无效令牌", http.StatusUnauthorized)
return
}
// 设置用户信息到上下文
userID := s.extractUserID(authHeader)
ctx := context.WithValue(r.Context(), "user_id", userID)
next.ServeHTTP(w, r.WithContext(ctx))
})
}
// 响应记录器
type responseRecorder struct {
http.ResponseWriter
statusCode int
}
func (rr *responseRecorder) WriteHeader(code int) {
rr.statusCode = code
rr.ResponseWriter.WriteHeader(code)
}
// 执行健康检查
func (s *HTTPServer) performHealthCheck() *HealthResult {
result := &HealthResult{
Status: "healthy",
Timestamp: time.Now(),
Checks: make(map[string]*CheckResult),
}
// 检查数据库连接
if err := s.checkDatabase(); err != nil {
result.Status = "unhealthy"
result.Checks["database"] = &CheckResult{
Status: "unhealthy",
Error: err.Error(),
}
} else {
result.Checks["database"] = &CheckResult{
Status: "healthy",
}
}
// 检查Redis连接
if err := s.checkRedis(); err != nil {
result.Status = "unhealthy"
result.Checks["redis"] = &CheckResult{
Status: "unhealthy",
Error: err.Error(),
}
} else {
result.Checks["redis"] = &CheckResult{
Status: "healthy",
}
}
return result
}
type HealthResult struct {
Status string `json:"status"`
Timestamp time.Time `json:"timestamp"`
Checks map[string]*CheckResult `json:"checks"`
}
type CheckResult struct {
Status string `json:"status"`
Error string `json:"error,omitempty"`
}
---
03.gRPC传输层实现
a.特性概述
a.Protocol Buffers集成
完整支持Protocol Buffers数据格式，提供高效的序列化性能。
b.流式传输
支持一元调用、客户端流式、服务端流式和双向流式四种调用模式。
c.拦截器机制
提供gRPC原生的拦截器机制，支持请求和响应的统一处理。
d.连接管理
高效的连接池管理，支持连接复用和负载均衡。
b.gRPC服务器配置
a.基础配置
监听地址、最大消息大小、超时设置等基础参数。
b.性能配置
连接参数、流控制、缓冲区大小等性能相关配置。
c.安全配置
TLS加密、认证授权等安全相关配置。
d.gRPC服务器示例
---
// gRPC传输层实现示例
package grpc
import (
"context"
"net"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/keepalive"
"google.golang.org/grpc/credentials"
"google.golang.org/grpc/health"
"google.golang.org/grpc/health/grpc_health_v1"
"google.golang.org/grpc/reflection"
)
// gRPC服务器配置
type GRPCServerConfig struct {
Address string `json:"address"`
MaxRecvMsgSize int `json:"max_recv_msg_size"`
MaxSendMsgSize int `json:"max_send_msg_size"`
ReadTimeout time.Duration `json:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout"`
KeepaliveParams keepalive.ServerParameters
TLS *TLSConfig `json:"tls,omitempty"`
EnableReflection bool `json:"enable_reflection"`
EnableHealthCheck bool `json:"enable_health_check"`
Interceptors []string `json:"interceptors"`
}
// gRPC服务器实现
type GRPCServer struct {
config *GRPCServerConfig
server *grpc.Server
listeners []net.Listener
healthServer *health.Server
ctx context.Context
cancel context.CancelFunc
}
// 创建gRPC服务器
func NewGRPCServer(config *GRPCServerConfig) *GRPCServer {
ctx, cancel := context.WithCancel(context.Background())
server := &GRPCServer{
config: config,
ctx: ctx,
cancel: cancel,
}
server.setupGRPCServer()
server.setupHealthServer()
return server
}
// 设置gRPC服务器
func (s *GRPCServer) setupGRPCServer() {
// 创建服务器选项
opts := []grpc.ServerOption{
// 消息大小限制
grpc.MaxRecvMsgSize(s.config.MaxRecvMsgSize),
grpc.MaxSendMsgSize(s.config.MaxSendMsgSize),
// 连接参数
grpc.KeepaliveParams(s.config.KeepaliveParams),
grpc.KeepaliveEnforcementPolicy(keepalive.EnforcementPolicy{
MinTime: 10 * time.Second,
PermitWithoutStream: true,
}),
// 流控制
grpc.InitialWindowSize(64 * 1024),
grpc.InitialConnWindowSize(128 * 1024),
grpc.WriteBufferSize(32 * 1024),
grpc.ReadBufferSize(32 * 1024),
// 拦截器
grpc.UnaryInterceptor(s.unaryServerInterceptor()),
grpc.StreamInterceptor(s.streamServerInterceptor()),
}
// 配置TLS
if s.config.TLS != nil {
creds, err := credentials.NewServerTLSFromFile(
s.config.TLS.CertFile,
s.config.TLS.KeyFile,
)
if err != nil {
panic(fmt.Sprintf("加载TLS证书失败: %s", err.Error()))
}
opts = append(opts, grpc.Creds(creds))
}
// 创建gRPC服务器
s.server = grpc.NewServer(opts...)
// 启用反射
if s.config.EnableReflection {
reflection.Register(s.server)
}
// 启用健康检查
if s.config.EnableHealthCheck {
grpc_health_v1.RegisterHealthServer(s.server, s.healthServer)
}
}
// 设置健康检查服务器
func (s *GRPCServer) setupHealthServer() {
s.healthServer = health.NewServer()
}
// 一元调用拦截器
func (s *GRPCServer) unaryServerInterceptor() grpc.UnaryServerInterceptor {
return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
start := time.Now()
// 记录请求开始
log.Printf("开始处理gRPC一元调用: %s", info.FullMethod)
// 添加追踪信息
ctx = s.addTracingContext(ctx, info.FullMethod)
// 执行业务逻辑
resp, err := handler(ctx, req)
// 记录请求完成
duration := time.Since(start)
log.Printf("完成gRPC一元调用: %s, 耗时: %v, 错误: %v", info.FullMethod, duration, err)
// 记录性能指标
s.recordGRPCMetrics(info.FullMethod, duration, err)
return resp, err
}
}
// 流式调用拦截器
func (s *GRPCServer) streamServerInterceptor() grpc.StreamServerInterceptor {
return func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
start := time.Now()
// 记录流式调用开始
log.Printf("开始处理gRPC流式调用: %s", info.FullMethod)
// 包装流以监控流量
wrappedStream := &monitoredServerStream{
ServerStream: ss,
info: info,
startTime: start,
}
err := handler(srv, wrappedStream)
duration := time.Since(start)
log.Printf("完成gRPC流式调用: %s, 耗时: %v, 错误: %v", info.FullMethod, duration, err)
s.recordGRPCMetrics(info.FullMethod, duration, err)
return err
}
}
// 监控服务流包装器
type monitoredServerStream struct {
grpc.ServerStream
info *grpc.StreamServerInfo
startTime time.Time
}
func (s *monitoredServerStream) RecvMsg(m interface{}) error {
err := s.ServerStream.RecvMsg(m)
if err == nil {
// 记录接收到的消息大小
size := estimateMessageSize(m)
s.recordMessageMetrics("recv", size)
}
return err
}
func (s *monitoredServerStream) SendMsg(m interface{}) error {
size := estimateMessageSize(m)
s.recordMessageMetrics("send", size)
err := s.ServerStream.SendMsg(m)
if err != nil {
log.Printf("发送消息失败: %s, 错误: %v", s.info.FullMethod, err)
}
return err
}
// 估算消息大小
func estimateMessageSize(m interface{}) int {
// 简单的大小估算，实际使用中可以使用更精确的方法
data, _ := json.Marshal(m)
return len(data)
}
// 记录消息指标
func (s *monitoredServerStream) recordMessageMetrics(direction string, size int) {
// 这里可以记录消息大小、数量等指标
log.Printf("gRPC流消息: %s, 方向: %s, 大小: %d", s.info.FullMethod, direction, size)
}
// 启动gRPC服务器
func (s *GRPCServer) Start(ctx context.Context) error {
// 创建监听器
listener, err := net.Listen("tcp", s.config.Address)
if err != nil {
return fmt.Errorf("创建监听器失败: %s", err.Error())
}
s.listeners = append(s.listeners, listener)
log.Printf("gRPC服务器启动在: %s", s.config.Address)
// 启动健康检查服务
s.healthServer.SetServingStatus("", grpc_health_v1.HealthCheckResponse_SERVING)
// 启动服务器
go func() {
<-ctx.Done()
log.Printf("正在停止gRPC服务器...")
s.healthServer.Shutdown()
s.server.GracefulStop()
}()
return s.server.Serve(listener)
}
// 停止gRPC服务器
func (s *GRPCServer) Stop(ctx context.Context) error {
s.cancel()
s.healthServer.Shutdown()
return s.server.GracefulStop()
}
// 注册gRPC服务
func (s *GRPCServer) RegisterService(desc *grpc.ServiceDesc, impl interface{}) {
s.server.RegisterService(desc, impl)
}
// 添加追踪上下文
func (s *GRPCServer) addTracingContext(ctx context.Context, method string) context.Context {
// 这里可以添加分布式追踪信息
return ctx
}
// 记录gRPC指标
func (s *GRPCServer) recordGRPCMetrics(method string, duration time.Duration, err error) {
// 这里可以记录请求数量、延迟、错误率等指标
status := "success"
if err != nil {
status = "error"
}
log.Printf("gRPC指标: 方法=%s, 耗时=%v, 状态=%s", method, duration, status)
}
// 用户服务gRPC实现示例
func (s *GRPCServer) RegisterUserService(userService UserServiceServer) {
// 假设这是用户服务的gRPC注册
// pb.RegisterUserServiceServer(s.server, userService)
log.Printf("注册用户服务到gRPC服务器")
}
// UserServiceServer接口定义
type UserServiceServer interface {
CreateUser(context.Context, *CreateUserRequest) (*CreateUserResponse, error)
GetUser(context.Context, *GetUserRequest) (*GetUserResponse, error)
UpdateUser(context.Context, *UpdateUserRequest) (*UpdateUserResponse, error)
DeleteUser(context.Context, *DeleteUserRequest) (*DeleteUserResponse, error)
}
// 创建用户请求
type CreateUserRequest struct {
Username string `json:"username"`
Email string `json:"email"`
Password string `json:"password"`
FullName string `json:"full_name"`
}
// 创建用户响应
type CreateUserResponse struct {
UserId string `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
}
// 获取用户请求
type GetUserRequest struct {
UserId string `json:"user_id"`
}
// 获取用户响应
type GetUserResponse struct {
UserId string `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
FullName string `json:"full_name"`
Status string `json:"status"`
}
// 更新用户请求
type UpdateUserRequest struct {
UserId string `json:"user_id"`
Email string `json:"email"`
FullName string `json:"full_name"`
}
// 更新用户响应
type UpdateUserResponse struct {
UserId string `json:"user_id"`
Username string `json:"username"`
Email string `json:"email"`
FullName string `json:"full_name"`
}
// 删除用户请求
type DeleteUserRequest struct {
UserId string `json:"user_id"`
}
// 删除用户响应
type DeleteUserResponse struct{}
---
04.传输层中间件系统
a.中间件架构
a.链式处理
支持多个中间件的链式组合和处理。
b.上下文传递
在中间件链中传递请求上下文和元数据。
c.错误处理
统一的错误处理和错误传播机制。
d.生命周期管理
中间件的生命周期管理和资源清理。
b.内置中间件
a.认证中间件
支持多种认证方式，包括JWT、OAuth2等。
b.授权中间件
基于角色和权限的访问控制。
c.限流中间件
支持多种限流算法，保护服务免受过载。
d.熔断中间件
实现熔断模式，防止级联故障。
e.中间件示例
---
// 传输层中间件系统示例
package middleware
import (
"context"
"net/http"
"time"
"github.com/go-kratos/kratos/v2/middleware"
"golang.org/x/time/rate"
)
// 中间件接口
type Middleware interface {
Process(ctx context.Context, req Request) (Response, error)
}
// 请求抽象
type Request struct {
Header http.Header
Body []byte
Method string
Path string
Query map[string][]string
Context context.Context
Metadata map[string]interface{}
}
// 响应抽象
type Response struct {
Header http.Header
Body []byte
Status int
}
// 中间件链
type MiddlewareChain struct {
middlewares []Middleware
index int
}
func NewChain(middlewares ...Middleware) *MiddlewareChain {
return &MiddlewareChain{
middlewares: middlewares,
index: 0,
}
}
func (c *MiddlewareChain) Next(ctx context.Context, req Request) (Response, error) {
if c.index >= len(c.middlewares) {
return Response{}, nil // 没有更多中间件
}
middleware := c.middlewares[c.index]
c.index++
return middleware.Process(ctx, req)
}
// 认证中间件
type AuthMiddleware struct {
secretKey string
tokenExpiry time.Duration
refreshExpiry time.Duration
}
func NewAuthMiddleware(secretKey string, tokenExpiry, refreshExpiry time.Duration) *AuthMiddleware {
return &AuthMiddleware{
secretKey: secretKey,
tokenExpiry: tokenExpiry,
refreshExpiry: refreshExpiry,
}
}
func (m *AuthMiddleware) Process(ctx context.Context, req Request) (Response, error) {
// 检查是否跳过认证
if m.shouldSkipAuth(req.Path) {
return Response{}, nil
}
// 从请求头获取令牌
authHeader := req.Header.Get("Authorization")
if authHeader == "" {
return Response{Status: http.StatusUnauthorized}, fmt.Errorf("缺少认证令牌")
}
// 验证令牌
claims, err := m.validateToken(authHeader)
if err != nil {
return Response{Status: http.StatusUnauthorized}, fmt.Errorf("无效令牌: %s", err.Error())
}
// 将用户信息添加到上下文
ctx = context.WithValue(ctx, "user_id", claims.UserID)
ctx = context.WithValue(ctx, "user_role", claims.Role)
req.Context = ctx
return Response{}, nil
}
func (m *AuthMiddleware) shouldSkipAuth(path string) bool {
// 定义不需要认证的路径
skipPaths := []string{
"/health",
"/ready",
"/metrics",
"/api/v1/auth/login",
"/api/v1/auth/register",
}
for _, skipPath := range skipPaths {
if path == skipPath {
return true
}
}
return false
}
// JWT声明
type JWTClaims struct {
UserID string `json:"user_id"`
Username string `json:"username"`
Role string `json:"role"`
Scopes []string `json:"scopes"`
}
// 限流中间件
type RateLimitMiddleware struct {
limiter *rate.Limiter
burst int
rate rate.Limit
}
func NewRateLimitMiddleware(rps int, burst int) *RateLimitMiddleware {
return &RateLimitMiddleware{
limiter: rate.NewLimiter(rate.Limit(rps), burst),
burst: burst,
rate: rate.Limit(rps),
}
}
func (m *RateLimitMiddleware) Process(ctx context.Context, req Request) (Response, error) {
if !m.limiter.Allow() {
return Response{
Status: http.StatusTooManyRequests,
Body: []byte(`{"error": "请求过于频繁，请稍后重试"}`),
Header: http.Header{"Content-Type": []string{"application/json"}},
}, nil
}
return Response{}, nil
}
// 熔断中间件
type CircuitBreakerMiddleware struct {
breakers map[string]*CircuitBreaker
mutex sync.RWMutex
}
type CircuitBreaker struct {
name string
maxRequests uint32
interval time.Duration
timeout time.Duration
readyToTrip func(counts CircuitBreakerCounts) bool
onStateChange func(name string, from, to CircuitBreakerState)
counts CircuitBreakerCounts
state CircuitBreakerState
generation uint64
mutex sync.Mutex
}
type CircuitBreakerState int
const (
CircuitBreakerClosed CircuitBreakerState = iota
CircuitBreakerHalfOpen
CircuitBreakerOpen
)
type CircuitBreakerCounts struct {
Requests uint32
TotalSuccesses uint32
TotalFailures uint32
ConsecutiveSuccesses uint32
ConsecutiveFailures uint32
}
func NewCircuitBreakerMiddleware() *CircuitBreakerMiddleware {
return &CircuitBreakerMiddleware{
breakers: make(map[string]*CircuitBreaker),
}
}
func (m *CircuitBreakerMiddleware) Process(ctx context.Context, req Request) (Response, error) {
key := m.getCircuitBreakerKey(req.Method, req.Path)
breaker := m.getOrCreateBreaker(key)
result, err := breaker.Execute(func() (interface{}, error) {
return nil, nil // 这里应该调用下一个中间件
})
if err != nil {
return Response{Status: http.StatusServiceUnavailable}, err
}
return Response{}, nil
}
func (m *CircuitBreakerMiddleware) getCircuitBreakerKey(method, path string) string {
return fmt.Sprintf("%s:%s", method, path)
}
func (m *CircuitBreakerMiddleware) getOrCreateBreaker(key string) *CircuitBreaker {
m.mutex.RLock()
breaker, exists := m.breakers[key]
m.mutex.RUnlock()
if exists {
return breaker
}
m.mutex.Lock()
defer m.mutex.Unlock()
// 双重检查
if breaker, exists := m.breakers[key]; exists {
return breaker
}
breaker = NewCircuitBreaker(key)
m.breakers[key] = breaker
return breaker
}
func NewCircuitBreaker(name string) *CircuitBreaker {
return &CircuitBreaker{
name: name,
maxRequests: 5,
interval: 60 * time.Second,
timeout: 30 * time.Second,
readyToTrip: func(counts CircuitBreakerCounts) bool {
failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
return counts.Requests >= 10 && failureRatio >= 0.6
},
onStateChange: func(name string, from, to CircuitBreakerState) {
log.Printf("熔断器状态变更: %s %s -> %s", name, from, to)
},
}
}
func (cb *CircuitBreaker) Execute(req func() (interface{}, error)) (interface{}, error) {
// 简化的熔断器实现
generation, err := cb.beforeRequest()
if err != nil {
return nil, err
}
defer cb.afterRequest(generation, err == nil)
result, err := req()
return result, err
}
func (cb *CircuitBreaker) beforeRequest() (uint64, error) {
cb.mutex.Lock()
defer cb.mutex.Unlock()
now := time.Now()
state, generation := cb.currentState(now)
if state == CircuitBreakerOpen {
return generation, fmt.Errorf("熔断器开启")
}
cb.counts.Requests++
return generation, nil
}
func (cb *CircuitBreaker) afterRequest(before uint64, success bool) {
cb.mutex.Lock()
defer cb.mutex.Unlock()
now := time.Now()
state, generation := cb.currentState(now)
if generation != before {
return
}
if success {
cb.onSuccess(state, now)
} else {
cb.onFailure(state, now)
}
}
func (cb *CircuitBreaker) onSuccess(state CircuitBreakerState, now time.Time) {
cb.counts.TotalSuccesses++
cb.counts.ConsecutiveSuccesses++
if state == CircuitBreakerHalfOpen && cb.counts.ConsecutiveSuccesses >= cb.maxRequests {
cb.setState(CircuitBreakerClosed, now)
}
}
func (cb *CircuitBreaker) onFailure(state CircuitBreakerState, now time.Time) {
cb.counts.TotalFailures++
cb.counts.ConsecutiveFailures++
if cb.readyToTrip(cb.counts) {
cb.setState(CircuitBreakerOpen, now)
}
}
func (cb *CircuitBreaker) currentState(now time.Time) (CircuitBreakerState, uint64) {
switch cb.state {
case CircuitBreakerClosed:
if !cb.expiry.IsZero() && cb.expiry.Before(now) {
cb.toNewGeneration(now)
}
case CircuitBreakerOpen:
if cb.expiry.Before(now) {
cb.setState(CircuitBreakerHalfOpen, now)
}
}
return cb.state, cb.generation
}
func (cb *CircuitBreaker) setState(state CircuitBreakerState, now time.Time) {
if cb.state == state {
return
}
prev := cb.state
cb.state = state
cb.toNewGeneration(now)
if cb.onStateChange != nil {
cb.onStateChange(cb.name, prev, state)
}
}
func (cb *CircuitBreaker) toNewGeneration(now time.Time) {
cb.generation++
cb.counts = CircuitBreakerCounts{}
var zero time.Time
switch cb.state {
case CircuitBreakerClosed:
if cb.interval == 0 {
cb.expiry = zero
} else {
cb.expiry = now.Add(cb.interval)
}
case CircuitBreakerOpen:
cb.expiry = now.Add(cb.timeout)
default: // CircuitBreakerHalfOpen
cb.expiry = zero
}
}
---
05.传输层性能优化
a.连接管理优化
a.连接池
实现HTTP和gRPC的连接池，复用TCP连接。
b.Keep-Alive
启用TCP Keep-Alive，减少连接建立和销毁的开销。
c.连接超时
合理设置连接超时，避免长时间占用资源。
b.数据传输优化
a.压缩传输
支持Gzip、Deflate等压缩算法，减少网络传输量。
b.流式传输
对于大数据量传输，使用流式传输减少内存占用。
c.数据缓存
实现响应缓存，减少重复计算和数据库访问。
c.并发优化
a.协程池
使用协程池处理并发请求，避免过度创建协程。
b.背压控制
实现背压控制机制，防止内存溢出。
c.负载均衡
支持多种负载均衡算法，优化请求分发。
---
// 传输层性能优化示例
package optimization
import (
"context"
"net/http"
"sync"
"time"
)
// 连接池管理器
type ConnectionPoolManager struct {
httpPools map[string]*HTTPConnectionPool
grpcPools map[string]*GRPCConnectionPool
mutex sync.RWMutex
config *PoolConfig
}
type PoolConfig struct {
MaxIdleConns int `json:"max_idle_conns"`
MaxActiveConns int `json:"max_active_conns"`
ConnMaxLifetime time.Duration `json:"conn_max_lifetime"`
ConnIdleTimeout time.Duration `json:"conn_idle_timeout"`
TestOnBorrow bool `json:"test_on_borrow"`
TestOnReturn bool `json:"test_on_return"`
}
func NewConnectionPoolManager(config *PoolConfig) *ConnectionPoolManager {
return &ConnectionPoolManager{
httpPools: make(map[string]*HTTPConnectionPool),
grpcPools: make(map[string]*GRPCConnectionPool),
config: config,
}
}
// HTTP连接池
type HTTPConnectionPool struct {
connections chan *http.Client
factory ConnectionFactory
mutex sync.Mutex
config *PoolConfig
}
type ConnectionFactory interface {
Create() (*http.Client, error)
Validate(client *http.Client) bool
Close(client *http.Client) error
}
func NewHTTPConnectionPool(factory ConnectionFactory, config *PoolConfig) *HTTPConnectionPool {
pool := &HTTPConnectionPool{
connections: make(chan *http.Client, config.MaxIdleConns),
factory: factory,
config: config,
}
// 预热连接池
pool.warmup()
return pool
}
func (p *HTTPConnectionPool) warmup() {
for i := 0; i < p.config.MaxIdleConns; i++ {
client, err := p.factory.Create()
if err != nil {
log.Printf("创建HTTP连接失败: %v", err)
continue
}
select {
case p.connections <- client:
default:
p.factory.Close(client)
}
}
}
func (p *HTTPConnectionPool) Get() (*http.Client, error) {
p.mutex.Lock()
defer p.mutex.Unlock()
select {
case client := <-p.connections:
if p.config.TestOnBorrow && !p.factory.Validate(client) {
p.factory.Close(client)
return p.Get() // 递归获取
}
return client, nil
default:
// 没有可用的连接，创建新的
return p.factory.Create()
}
}
func (p *HTTPConnectionPool) Put(client *http.Client) {
p.mutex.Lock()
defer p.mutex.Unlock()
if p.config.TestOnReturn && !p.factory.Validate(client) {
p.factory.Close(client)
return
}
select {
case p.connections <- client:
default:
// 连接池已满，关闭连接
p.factory.Close(client)
}
}
// 压缩中间件
type CompressionMiddleware struct {
level int
minContentLen int
types []string
}
func NewCompressionMiddleware(level, minContentLen int, types []string) *CompressionMiddleware {
return &CompressionMiddleware{
level: level,
minContentLen: minContentLen,
types: types,
}
}
func (m *CompressionMiddleware) Process(ctx context.Context, req Request) (Response, error) {
// 检查是否需要压缩
if !m.shouldCompress(req.Header, req.Body) {
return Response{}, nil
}
// 压缩响应体
compressed, err := m.compress(req.Body)
if err != nil {
return Response{}, err
}
return Response{
Body: compressed,
Header: http.Header{
"Content-Encoding": []string{"gzip"},
"Content-Length": []string{fmt.Sprintf("%d", len(compressed))},
},
}, nil
}
func (m *CompressionMiddleware) shouldCompress(header http.Header, body []byte) bool {
// 检查客户端是否支持压缩
acceptEncoding := header.Get("Accept-Encoding")
if !strings.Contains(acceptEncoding, "gzip") {
return false
}
// 检查内容长度
if len(body) < m.minContentLen {
return false
}
// 检查内容类型
contentType := header.Get("Content-Type")
for _, t := range m.types {
if strings.Contains(contentType, t) {
return true
}
}
return false
}
func (m *CompressionMiddleware) compress(data []byte) ([]byte, error) {
var buf bytes.Buffer
gz := gzip.NewWriterLevel(&buf, m.level)
if _, err := gz.Write(data); err != nil {
return nil, err
}
if err := gz.Close(); err != nil {
return nil, err
}
return buf.Bytes(), nil
}
// 协程池处理器
type GoroutinePool struct {
workerCount int
taskQueue chan func()
wg sync.WaitGroup
ctx context.Context
cancel context.CancelFunc
}
func NewGoroutinePool(workerCount int) *GoroutinePool {
ctx, cancel := context.WithCancel(context.Background())
pool := &GoroutinePool{
workerCount: workerCount,
taskQueue: make(chan func(), workerCount*2), // 缓冲队列
ctx: ctx,
cancel: cancel,
}
pool.start()
return pool
}
func (p *GoroutinePool) start() {
for i := 0; i < p.workerCount; i++ {
p.wg.Add(1)
go p.worker()
}
}
func (p *GoroutinePool) worker() {
defer p.wg.Done()
for {
select {
case task := <-p.taskQueue:
if task != nil {
task()
}
case <-p.ctx.Done():
return
}
}
}
func (p *GoroutinePool) Submit(task func()) {
select {
case p.taskQueue <- task:
default:
// 队列已满，直接执行
go task()
}
}
func (p *GoroutinePool) Close() {
p.cancel()
close(p.taskQueue)
p.wg.Wait()
}
// 背压控制器
type BackpressureController struct {
maxQueueSize int
currentQueue int
mutex sync.Mutex
rejectedCount int64
acceptedCount int64
}
func NewBackpressureController(maxQueueSize int) *BackpressureController {
return &BackpressureController{
maxQueueSize: maxQueueSize,
}
}
func (c *BackpressureController) Accept() bool {
c.mutex.Lock()
defer c.mutex.Unlock()
if c.currentQueue >= c.maxQueueSize {
atomic.AddInt64(&c.rejectedCount, 1)
return false
}
c.currentQueue++
atomic.AddInt64(&c.acceptedCount, 1)
return true
}
func (c *BackpressureController) Release() {
c.mutex.Lock()
defer c.mutex.Unlock()
if c.currentQueue > 0 {
c.currentQueue--
}
}
func (c *BackpressureController) GetStats() BackpressureStats {
c.mutex.Lock()
defer c.mutex.Unlock()
return BackpressureStats{
CurrentQueue: c.currentQueue,
MaxQueueSize: c.maxQueueSize,
RejectedCount: atomic.LoadInt64(&c.rejectedCount),
AcceptedCount: atomic.LoadInt64(&c.acceptedCount),
}
}
type BackpressureStats struct {
CurrentQueue int `json:"current_queue"`
MaxQueueSize int `json:"max_queue_size"`
RejectedCount int64 `json:"rejected_count"`
AcceptedCount int64 `json:"accepted_count"`
}
---
2.3 应用生命周期组件 Application
01.应用生命周期架构
a.生命周期阶段
a.初始化阶段
应用组件的初始化和依赖注入。
b.启动阶段
服务的启动和健康检查注册。
c.运行阶段
正常处理请求的业务逻辑。
d.停止阶段
优雅关闭和资源清理。
b.生命周期回调
a.BeforeStart回调
应用启动前的预处理。
b.AfterStart回调
应用启动完成后的后处理。
c.BeforeStop回调
应用停止前的预处理。
d.AfterStop回调
应用停止完成后的后处理。
c.应用生命周期示例
---
// Application应用生命周期架构示例
package application
import (
"context"
"fmt"
"os"
"os/signal"
"sync"
"syscall"
"time"
"github.com/go-kratos/kratos/v2"
)
// 生命周期阶段
type LifecyclePhase int
const (
PhaseUninitialized LifecyclePhase = iota
PhaseInitializing
PhaseInitialized
PhaseStarting
PhaseStarted
PhaseRunning
PhaseStopping
PhaseStopped
PhaseTerminated
)
// 生命周期回调函数
type LifecycleCallback func(ctx context.Context) error
// 应用接口
type Application interface {
// 启动应用
Run() error
// 停止应用
Stop(ctx context.Context) error
// 获取应用状态
State() ApplicationState
// 等待应用结束
Wait() <-chan error
}
// 应用状态
type ApplicationState struct {
Phase LifecyclePhase `json:"phase"`
StartTime time.Time `json:"start_time"`
Version string `json:"version"`
Metadata map[string]string `json:"metadata"`
Components map[string]interface{} `json:"components"`
}
// Kratos应用实现
type KratosApplication struct {
app *kratos.App
state ApplicationState
callbacks map[string][]LifecycleCallback
mutex sync.RWMutex
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
doneChan chan struct{}
errorChan chan error
stopOnce sync.Once
isRunning bool
shutdownHooks []ShutdownHook
}
// 关闭钩子
type ShutdownHook struct {
Name string
Order int
Timeout time.Duration
Func func(ctx context.Context) error
}
// 创建Kratos应用
func NewKratosApplication(opts ...kratos.Option) *KratosApplication {
ctx, cancel := context.WithCancel(context.Background())
app := &KratosApplication{
app: kratos.New(opts...),
state: ApplicationState{
Phase: PhaseUninitialized,
Metadata: make(map[string]string),
Components: make(map[string]interface{}),
},
callbacks: make(map[string][]LifecycleCallback),
ctx: ctx,
cancel: cancel,
doneChan: make(chan struct{}),
errorChan: make(chan error, 1),
shutdownHooks: make([]ShutdownHook, 0),
}
// 设置信号处理
app.setupSignalHandling()
return app
}
// 运行应用
func (a *KratosApplication) Run() error {
a.mutex.Lock()
defer a.mutex.Unlock()
if a.isRunning {
return fmt.Errorf("应用已在运行")
}
// 初始化阶段
if err := a.executePhase("before_start", PhaseInitializing); err != nil {
return fmt.Errorf("执行启动前回调失败: %s", err.Error())
}
// 启动应用
a.state.Phase = PhaseStarting
a.state.StartTime = time.Now()
// 在后台启动应用
a.wg.Add(1)
go func() {
defer a.wg.Done()
if err := a.app.Run(); err != nil {
a.errorChan <- fmt.Errorf("应用启动失败: %s", err.Error())
}
}()
// 等待启动完成
time.Sleep(100 * time.Millisecond) // 给应用一些时间启动
// 执行启动后回调
if err := a.executePhase("after_start", PhaseStarted); err != nil {
return fmt.Errorf("执行启动后回调失败: %s", err.Error())
}
a.state.Phase = PhaseRunning
a.isRunning = true
// 等待应用结束
return <-a.errorChan
}
// 停止应用
func (a *KratosApplication) Stop(ctx context.Context) error {
var stopErr error
a.stopOnce.Do(func() {
a.mutex.Lock()
defer a.mutex.Unlock()
if !a.isRunning {
return
}
a.state.Phase = PhaseStopping
// 执行停止前回调
if err := a.executePhase("before_stop", PhaseStopping); err != nil {
stopErr = fmt.Errorf("执行停止前回调失败: %s", err.Error())
}
// 执行关闭钩子
if err := a.executeShutdownHooks(ctx); err != nil {
stopErr = fmt.Errorf("执行关闭钩子失败: %s", err.Error())
}
// 停止Kratos应用
if err := a.app.Stop(ctx); err != nil {
stopErr = fmt.Errorf("停止应用失败: %s", err.Error())
}
// 取消上下文
a.cancel()
// 等待所有goroutine完成
done := make(chan struct{})
go func() {
a.wg.Wait()
close(done)
}()
select {
case <-done:
// 正常完成
case <-time.After(30 * time.Second):
// 超时
stopErr = fmt.Errorf("等待应用关闭超时")
}
a.state.Phase = PhaseStopped
a.isRunning = false
close(a.doneChan)
})
return stopErr
}
// 获取应用状态
func (a *KratosApplication) State() ApplicationState {
a.mutex.RLock()
defer a.mutex.RUnlock()
state := a.state
state.Components = make(map[string]interface{})
for k, v := range a.state.Components {
state.Components[k] = v
}
return state
}
// 等待应用结束
func (a *KratosApplication) Wait() <-chan error {
return a.errorChan
}
// 添加生命周期回调
func (a *KratosApplication) AddCallback(phase string, callback LifecycleCallback) {
a.mutex.Lock()
defer a.mutex.Unlock()
a.callbacks[phase] = append(a.callbacks[phase], callback)
}
// 添加关闭钩子
func (a *KratosApplication) AddShutdownHook(hook ShutdownHook) {
a.mutex.Lock()
defer a.mutex.Unlock()
a.shutdownHooks = append(a.shutdownHooks, hook)
// 按Order排序
sort.Slice(a.shutdownHooks, func(i, j int) bool {
return a.shutdownHooks[i].Order < a.shutdownHooks[j].Order
})
}
// 设置元数据
func (a *KratosApplication) SetMetadata(key, value string) {
a.mutex.Lock()
defer a.mutex.Unlock()
a.state.Metadata[key] = value
}
// 注册组件
func (a *KratosApplication) RegisterComponent(name string, component interface{}) {
a.mutex.Lock()
defer a.mutex.Unlock()
a.state.Components[name] = component
}
// 执行生命周期阶段
func (a *KratosApplication) executePhase(phase string, newPhase LifecyclePhase) error {
callbacks := a.callbacks[phase]
for _, callback := range callbacks {
if err := callback(a.ctx); err != nil {
return err
}
}
a.state.Phase = newPhase
return nil
}
// 执行关闭钩子
func (a *KratosApplication) executeShutdownHooks(ctx context.Context) error {
for _, hook := range a.shutdownHooks {
hookCtx := ctx
if hook.Timeout > 0 {
var cancel context.CancelFunc
hookCtx, cancel = context.WithTimeout(ctx, hook.Timeout)
defer cancel()
}
if err := hook.Func(hookCtx); err != nil {
return fmt.Errorf("关闭钩子 %s 执行失败: %s", hook.Name, err.Error())
}
}
return nil
}
// 设置信号处理
func (a *KratosApplication) setupSignalHandling() {
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
go func() {
sig := <-sigChan
fmt.Printf("接收到信号: %v，开始优雅关闭...\n", sig)
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := a.Stop(ctx); err != nil {
a.errorChan <- fmt.Errorf("优雅关闭失败: %s", err.Error())
}
}()
}
// 应用构建器
type ApplicationBuilder struct {
options []kratos.Option
config *AppConfig
}
// 应用配置
type AppConfig struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
Metadata map[string]string `json:"metadata"`
}
// 创建应用构建器
func NewApplicationBuilder() *ApplicationBuilder {
return &ApplicationBuilder{
options: make([]kratos.Option, 0),
config: &AppConfig{
Metadata: make(map[string]string),
},
}
}
// 设置应用名称
func (b *ApplicationBuilder) WithName(name string) *ApplicationBuilder {
b.config.Name = name
b.options = append(b.options, kratos.Name(name))
return b
}
// 设置应用版本
func (b *ApplicationBuilder) WithVersion(version string) *ApplicationBuilder {
b.config.Version = version
b.options = append(b.options, kratos.Version(version))
return b
}
// 设置元数据
func (b *ApplicationBuilder) WithMetadata(metadata map[string]string) *ApplicationBuilder {
for k, v := range metadata {
b.config.Metadata[k] = v
}
b.options = append(b.options, kratos.Metadata(metadata))
return b
}
// 添加服务器
func (b *ApplicationBuilder) WithServer(servers ...kratos.Server) *ApplicationBuilder {
b.options = append(b.options, kratos.Server(servers...))
return b
}
// 添加注册中心
func (b *ApplicationBuilder) WithRegistrar(registrar kratos.Registrar) *ApplicationBuilder {
b.options = append(b.options, kratos.Registrar(registrar))
return b
}
// 添加发现器
func (b *ApplicationBuilder) WithDiscovery(discovery kratos.Discovery) *ApplicationBuilder {
b.options = append(b.options, kratos.Discovery(discovery))
return b
}
// 添加日志器
func (b *ApplicationBuilder) WithLogger(logger log.Logger) *ApplicationBuilder {
b.options = append(b.options, kratos.Logger(logger))
return b
}
// 添加数据源
func (b *ApplicationBuilder) WithDataSource(ds kratos.DataSource) *ApplicationBuilder {
b.options = append(b.options, kratos.DataSource(ds))
return b
}
// 添加开始前回调
func (b *ApplicationBuilder) WithBeforeStart(callback LifecycleCallback) *ApplicationBuilder {
// 这个需要在构建应用后设置
return b
}
// 添加开始后回调
func (b *ApplicationBuilder) WithAfterStart(callback LifecycleCallback) *ApplicationBuilder {
return b
}
// 添加停止前回调
func (b *ApplicationBuilder) WithBeforeStop(callback LifecycleCallback) *ApplicationBuilder {
return b
}
// 添加停止后回调
func (b *ApplicationBuilder) WithAfterStop(callback LifecycleCallback) *ApplicationBuilder {
return b
}
// 构建应用
func (b *ApplicationBuilder) Build() *KratosApplication {
app := NewKratosApplication(b.options...)
// 设置元数据
for k, v := range b.config.Metadata {
app.SetMetadata(k, v)
}
return app
}
// 应用启动器
type ApplicationBootstrapper struct {
app *KratosApplication
bootstrapSteps []BootstrapStep
}
// 启动步骤
type BootstrapStep struct {
Name string
Func func(ctx context.Context, app *KratosApplication) error
Order int
Required bool
}
// 创建应用启动器
func NewApplicationBootstrapper(app *KratosApplication) *ApplicationBootstrapper {
return &ApplicationBootstrapper{
app: app,
bootstrapSteps: make([]BootstrapStep, 0),
}
}
// 添加启动步骤
func (b *ApplicationBootstrapper) AddStep(step BootstrapStep) {
b.bootstrapSteps = append(b.bootstrapSteps, step)
// 按Order排序
sort.Slice(b.bootstrapSteps, func(i, j int) bool {
return b.bootstrapSteps[i].Order < b.bootstrapSteps[j].Order
})
}
// 执行启动
func (b *ApplicationBootstrapper) Bootstrap(ctx context.Context) error {
for _, step := range b.bootstrapSteps {
fmt.Printf("执行启动步骤: %s\n", step.Name)
if err := step.Func(ctx, b.app); err != nil {
if step.Required {
return fmt.Errorf("启动步骤 %s 执行失败: %s", step.Name, err.Error())
}
fmt.Printf("启动步骤 %s 执行失败（可选）: %s\n", step.Name, err.Error())
} else {
fmt.Printf("启动步骤 %s 执行成功\n", step.Name)
}
}
return nil
}
---
02.启动和关闭管理
a.优雅启动
a.依赖检查
检查外部依赖是否可用。
b.预热缓存
预热缓存数据，提高初始响应速度。
c.健康检查注册
注册健康检查端点。
b.优雅关闭
a.请求处理完成
等待正在处理的请求完成。
b.连接关闭
优雅关闭数据库连接等资源。
c.服务注销
从注册中心注销服务。
c.信号处理
a.SIGINT处理
处理Ctrl+C信号。
b.SIGTERM处理
处理终止信号。
c.SIGHUP处理
处理重载配置信号。
d.启动关闭示例
---
// 启动和关闭管理示例
package lifecycle
import (
"context"
"fmt"
"sync"
"time"
)
// 启动管理器
type StartupManager struct {
app *KratosApplication
steps []StartupStep
mutex sync.RWMutex
timeout time.Duration
logger Logger
}
// 启动步骤
type StartupStep struct {
Name string
Description string
Func StartupFunc
Timeout time.Duration
Required bool
Dependencies []string
}
// 启动函数
type StartupFunc func(ctx context.Context) error
// 创建启动管理器
func NewStartupManager(app *KratosApplication, timeout time.Duration, logger Logger) *StartupManager {
return &StartupManager{
app: app,
steps: make([]StartupStep, 0),
timeout: timeout,
logger: logger,
}
}
// 添加启动步骤
func (m *StartupManager) AddStep(step StartupStep) {
m.mutex.Lock()
defer m.mutex.Unlock()
// 设置默认超时
if step.Timeout == 0 {
step.Timeout = m.timeout
}
m.steps = append(m.steps, step)
}
// 执行启动
func (m *StartupManager) Start(ctx context.Context) error {
m.mutex.RLock()
steps := make([]StartupStep, len(m.steps))
copy(steps, m.steps)
m.mutex.RUnlock()
// 解析依赖关系并排序
sortedSteps, err := m.sortStepsByDependencies(steps)
if err != nil {
return fmt.Errorf("解析启动步骤依赖失败: %s", err.Error())
}
// 执行启动步骤
for _, step := range sortedSteps {
if err := m.executeStep(ctx, step); err != nil {
return fmt.Errorf("启动步骤 %s 执行失败: %s", step.Name, err.Error())
}
m.logger.Infof("启动步骤 %s 执行成功", step.Name)
}
return nil
}
// 执行单个启动步骤
func (m *StartupManager) executeStep(ctx context.Context, step StartupStep) error {
m.logger.Infof("开始执行启动步骤: %s - %s", step.Name, step.Description)
// 设置超时
stepCtx := ctx
if step.Timeout > 0 {
var cancel context.CancelFunc
stepCtx, cancel = context.WithTimeout(ctx, step.Timeout)
defer cancel()
}
// 执行启动函数
if err := step.Func(stepCtx); err != nil {
if step.Required {
return fmt.Errorf("必需步骤 %s 执行失败: %s", step.Name, err.Error())
}
m.logger.Warnf("可选步骤 %s 执行失败: %s", step.Name, err.Error())
return nil
}
return nil
}
// 按依赖关系排序步骤
func (m *StartupManager) sortStepsByDependencies(steps []StartupStep) ([]StartupStep, error) {
stepMap := make(map[string]StartupStep)
nameMap := make(map[string]bool)
// 创建步骤映射
for _, step := range steps {
stepMap[step.Name] = step
nameMap[step.Name] = true
}
// 检查依赖是否存在
for _, step := range steps {
for _, dep := range step.Dependencies {
if !nameMap[dep] {
return nil, fmt.Errorf("步骤 %s 依赖的步骤 %s 不存在", step.Name, dep)
}
}
}
// 拓扑排序
return m.topologicalSort(steps, stepMap)
}
// 拓扑排序
func (m *StartupManager) topologicalSort(steps []StartupStep, stepMap map[string]StartupStep) ([]StartupStep, error) {
var result []StartupStep
visited := make(map[string]bool)
visiting := make(map[string]bool)
var visit func(stepName string) error
visit = func(stepName string) error {
if visited[stepName] {
return nil
}
if visiting[stepName] {
return fmt.Errorf("检测到循环依赖，涉及步骤: %s", stepName)
}
visiting[stepName] = true
step, exists := stepMap[stepName]
if !exists {
return fmt.Errorf("步骤不存在: %s", stepName)
}
// 先访问依赖
for _, dep := range step.Dependencies {
if err := visit(dep); err != nil {
return err
}
}
visiting[stepName] = false
visited[stepName] = true
result = append(result, step)
return nil
}
for _, step := range steps {
if err := visit(step.Name); err != nil {
return nil, err
}
}
return result, nil
}
// 关闭管理器
type ShutdownManager struct {
app *KratosApplication
hooks []ShutdownHook
mutex sync.RWMutex
timeout time.Duration
logger Logger
}
// 创建关闭管理器
func NewShutdownManager(app *KratosApplication, timeout time.Duration, logger Logger) *ShutdownManager {
return &ShutdownManager{
app: app,
hooks: make([]ShutdownHook, 0),
timeout: timeout,
logger: logger,
}
}
// 添加关闭钩子
func (m *ShutdownManager) AddHook(hook ShutdownHook) {
m.mutex.Lock()
defer m.mutex.Unlock()
// 设置默认超时
if hook.Timeout == 0 {
hook.Timeout = m.timeout
}
m.hooks = append(m.hooks, hook)
// 按Order排序
sort.Slice(m.hooks, func(i, j int) bool {
return m.hooks[i].Order < m.hooks[j].Order
})
}
// 执行关闭
func (m *ShutdownManager) Shutdown(ctx context.Context) error {
m.mutex.RLock()
hooks := make([]ShutdownHook, len(m.hooks))
copy(hooks, m.hooks)
m.mutex.RUnlock()
// 执行关闭钩子
for _, hook := range hooks {
if err := m.executeHook(ctx, hook); err != nil {
m.logger.Errorf("关闭钩子 %s 执行失败: %s", hook.Name, err.Error())
if hook.Order <= 100 { // 关键钩子失败则停止关闭
return fmt.Errorf("关键关闭钩子 %s 执行失败: %s", hook.Name, err.Error())
}
} else {
m.logger.Infof("关闭钩子 %s 执行成功", hook.Name)
}
}
return nil
}
// 执行单个关闭钩子
func (m *ShutdownManager) executeHook(ctx context.Context, hook ShutdownHook) error {
m.logger.Infof("开始执行关闭钩子: %s", hook.Name)
// 设置超时
hookCtx := ctx
if hook.Timeout > 0 {
var cancel context.CancelFunc
hookCtx, cancel = context.WithTimeout(ctx, hook.Timeout)
defer cancel()
}
// 执行关闭函数
if err := hook.Func(hookCtx); err != nil {
return fmt.Errorf("关闭钩子执行失败: %s", err.Error())
}
return nil
}
// 信号管理器
type SignalManager struct {
app *KratosApplication
sigChan chan os.Signal
shutdownMgr *ShutdownManager
reloadFunc ReloadFunc
logger Logger
}
// 重载函数
type ReloadFunc func(ctx context.Context) error
// 创建信号管理器
func NewSignalManager(app *KratosApplication, shutdownMgr *ShutdownManager, logger Logger) *SignalManager {
return &SignalManager{
app: app,
sigChan: make(chan os.Signal, 1),
shutdownMgr: shutdownMgr,
logger: logger,
}
}
// 设置重载函数
func (m *SignalManager) SetReloadFunc(reloadFunc ReloadFunc) {
m.reloadFunc = reloadFunc
}
// 启动信号监听
func (m *SignalManager) Start() {
signal.Notify(m.sigChan, syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP)
go m.handleSignals()
}
// 处理信号
func (m *SignalManager) handleSignals() {
for sig := range m.sigChan {
switch sig {
case syscall.SIGINT, syscall.SIGTERM:
m.logger.Infof("接收到信号 %v，开始优雅关闭", sig)
m.handleShutdown()
case syscall.SIGHUP:
if m.reloadFunc != nil {
m.logger.Infof("接收到信号 %v，开始重载配置", sig)
m.handleReload()
} else {
m.logger.Infof("接收到信号 %v，但未设置重载函数", sig)
}
}
}
}
// 处理关闭信号
func (m *SignalManager) handleShutdown() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := m.shutdownMgr.Shutdown(ctx); err != nil {
m.logger.Errorf("优雅关闭失败: %s", err.Error())
os.Exit(1)
}
m.logger.Info("优雅关闭完成")
os.Exit(0)
}
// 处理重载信号
func (m *SignalManager) handleReload() {
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := m.reloadFunc(ctx); err != nil {
m.logger.Errorf("重载配置失败: %s", err.Error())
} else {
m.logger.Info("重载配置成功")
}
}
// 健康检查管理器
type HealthCheckManager struct {
app *KratosApplication
checks map[string]HealthCheck
mutex sync.RWMutex
interval time.Duration
logger Logger
}
// 健康检查接口
type HealthCheck interface {
Name() string
Check(ctx context.Context) HealthStatus
}
// 健康状态
type HealthStatus struct {
Status string `json:"status"`
Message string `json:"message,omitempty"`
Details map[string]interface{} `json:"details,omitempty"`
}
// 创建健康检查管理器
func NewHealthCheckManager(app *KratosApplication, interval time.Duration, logger Logger) *HealthCheckManager {
return &HealthCheckManager{
app: app,
checks: make(map[string]HealthCheck),
interval: interval,
logger: logger,
}
}
// 添加健康检查
func (m *HealthCheckManager) AddCheck(check HealthCheck) {
m.mutex.Lock()
defer m.mutex.Unlock()
m.checks[check.Name()] = check
}
// 执行健康检查
func (m *HealthCheckManager) Check(ctx context.Context) map[string]HealthStatus {
m.mutex.RLock()
checks := make(map[string]HealthCheck)
for name, check := range m.checks {
checks[name] = check
}
m.mutex.RUnlock()
results := make(map[string]HealthStatus)
for name, check := range checks {
results[name] = check.Check(ctx)
}
return results
}
// 启动定期健康检查
func (m *HealthCheckManager) Start(ctx context.Context) {
ticker := time.NewTicker(m.interval)
defer ticker.Stop()
for {
select {
case <-ticker.C:
m.performHealthCheck(ctx)
case <-ctx.Done():
return
}
}
}
// 执行健康检查
func (m *HealthCheckManager) performHealthCheck(ctx context.Context) {
results := m.Check(ctx)
allHealthy := true
for name, status := range results {
if status.Status != "healthy" {
allHealthy = false
m.logger.Warnf("健康检查 %s 状态异常: %s - %s", name, status.Status, status.Message)
}
}
if allHealthy {
m.logger.Debug("所有健康检查通过")
}
}
---
2.4 配置管理组件 Config
01.配置管理架构设计
a.分层配置架构
a.数据源层
支持多种配置数据源，包括文件、环境变量、命令行参数、配置中心等。
b.解析层
负责不同格式配置文件的解析，支持YAML、JSON、TOML、XML等格式。
c.管理层
提供配置的统一管理接口，包括配置读取、写入、更新、删除等操作。
d.监听层
实现配置变更的监听和通知机制，支持配置热更新。
b.配置接口抽象
a.Source接口
定义配置数据源的抽象，支持多种数据源实现。
b.Parser接口
定义配置解析器的抽象，支持多种配置格式。
c.Watcher接口
定义配置监听器的抽象，实现配置变更通知。
c.配置组件示例
---
// Config配置管理组件架构示例
package config
import (
"context"
"fmt"
"os"
"path/filepath"
"sync"
"time"
"github.com/go-kratos/kratos/v2/config"
)
// 配置源接口
type ConfigSource interface {
// 读取配置
Load() ([]byte, error)
// 监听配置变更
Watch() (<-chan []byte, error)
// 关闭配置源
Close() error
// 获取源信息
Info() SourceInfo
}
// 配置源信息
type SourceInfo struct {
Type string `json:"type"`
Path string `json:"path"`
Encoding string `json:"encoding"`
Metadata map[string]string `json:"metadata"`
}
// 配置解析器接口
type ConfigParser interface {
// 解析配置
Parse(data []byte, v interface{}) error
// 格式化配置
Format(v interface{}) ([]byte, error)
// 支持的格式
Formats() []string
}
// 配置监听器接口
type ConfigWatcher interface {
// 开始监听
Start(ctx context.Context) error
// 停止监听
Stop() error
// 添加监听回调
AddWatcher(key string, callback ConfigChangeCallback) error
// 移除监听回调
RemoveWatcher(key string) error
}
// 配置变更回调
type ConfigChangeCallback func(key string, oldValue, newValue interface{})
// 配置管理器实现
type ConfigManager struct {
sources []ConfigSource
parsers map[string]ConfigParser
watchers []ConfigWatcher
data map[string]interface{}
mutex sync.RWMutex
callbacks map[string][]ConfigChangeCallback
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
}
// 创建配置管理器
func NewConfigManager() *ConfigManager {
ctx, cancel := context.WithCancel(context.Background())
return &ConfigManager{
sources: make([]ConfigSource, 0),
parsers: make(map[string]ConfigParser),
watchers: make([]ConfigWatcher, 0),
data: make(map[string]interface{}),
callbacks: make(map[string][]ConfigChangeCallback),
ctx: ctx,
cancel: cancel,
}
}
// 添加配置源
func (cm *ConfigManager) AddSource(source ConfigSource) error {
cm.mutex.Lock()
defer cm.mutex.Unlock()
cm.sources = append(cm.sources, source)
// 立即加载配置
data, err := source.Load()
if err != nil {
return fmt.Errorf("加载配置失败: %s", err.Error())
}
return cm.parseAndMerge(source.Info().Type, data)
}
// 注册配置解析器
func (cm *ConfigManager) RegisterParser(format string, parser ConfigParser) {
cm.mutex.Lock()
defer cm.mutex.Unlock()
cm.parsers[format] = parser
}
// 添加配置监听器
func (cm *ConfigManager) AddWatcher(watcher ConfigWatcher) error {
cm.mutex.Lock()
defer cm.mutex.Unlock()
cm.watchers = append(cm.watchers, watcher)
return watcher.Start(cm.ctx)
}
// 解析并合并配置
func (cm *ConfigManager) parseAndMerge(format string, data []byte) error {
parser, exists := cm.parsers[format]
if !exists {
return fmt.Errorf("不支持的配置格式: %s", format)
}
var configData interface{}
if err := parser.Parse(data, &configData); err != nil {
return fmt.Errorf("解析配置失败: %s", err.Error())
}
return cm.mergeConfig(configData)
}
// 合并配置数据
func (cm *ConfigManager) mergeConfig(newData interface{}) error {
cm.mutex.Lock()
defer cm.mutex.Unlock()
// 简化的配置合并逻辑
if newConfig, ok := newData.(map[string]interface{}); ok {
for key, value := range newConfig {
oldValue, exists := cm.data[key]
cm.data[key] = value
// 触发变更回调
if exists && cm.callbacks[key] != nil {
for _, callback := range cm.callbacks[key] {
go callback(key, oldValue, value)
}
}
}
}
return nil
}
// 获取配置值
func (cm *ConfigManager) Get(key string) (interface{}, bool) {
cm.mutex.RLock()
defer cm.mutex.RUnlock()
value, exists := cm.data[key]
return value, exists
}
// 设置配置值
func (cm *ConfigManager) Set(key string, value interface{}) {
cm.mutex.Lock()
defer cm.mutex.Unlock()
oldValue, exists := cm.data[key]
cm.data[key] = value
// 触发变更回调
if exists && cm.callbacks[key] != nil {
for _, callback := range cm.callbacks[key] {
go callback(key, oldValue, value)
}
}
}
// 添加变更回调
func (cm *ConfigManager) OnChange(key string, callback ConfigChangeCallback) {
cm.mutex.Lock()
defer cm.mutex.Unlock()
if cm.callbacks[key] == nil {
cm.callbacks[key] = make([]ConfigChangeCallback, 0)
}
cm.callbacks[key] = append(cm.callbacks[key], callback)
}
// 启动配置管理器
func (cm *ConfigManager) Start() error {
cm.wg.Add(1)
go cm.watchConfigChanges()
return nil
}
// 监听配置变更
func (cm *ConfigManager) watchConfigChanges() {
defer cm.wg.Done()
for _, source := range cm.sources {
cm.wg.Add(1)
go func(s ConfigSource) {
defer cm.wg.Done()
cm.watchSource(s)
}(source)
}
}
// 监听单个配置源
func (cm *ConfigManager) watchSource(source ConfigSource) {
ch, err := source.Watch()
if err != nil {
log.Printf("监听配置源失败: %s", err.Error())
return
}
for {
select {
case data := <-ch:
if data != nil {
if err := cm.parseAndMerge(source.Info().Type, data); err != nil {
log.Printf("解析配置变更失败: %s", err.Error())
}
}
case <-cm.ctx.Done():
return
}
}
}
// 关闭配置管理器
func (cm *ConfigManager) Close() error {
cm.cancel()
cm.wg.Wait()
for _, source := range cm.sources {
source.Close()
}
for _, watcher := range cm.watchers {
watcher.Stop()
}
return nil
}
---
02.配置源实现
a.文件配置源
a.本地文件
支持本地配置文件的读取和监听，包括YAML、JSON、TOML等格式。
b.配置热加载
监听配置文件的变更，自动重新加载配置。
c.文件验证
支持配置文件的格式验证和语法检查。
b.环境变量配置源
a.环境变量读取
从系统环境变量中读取配置值。
b.变量映射
支持环境变量到配置键的映射规则。
c.类型转换
自动进行环境变量值的类型转换。
c.命令行参数源
a.参数解析
解析命令行参数并转换为配置数据。
b.参数验证
支持命令行参数的格式验证和范围检查。
d.配置中心源
a.Consul配置中心
支持从Consul获取配置，并监听配置变更。
b.Nacos配置中心
集成Nacos配置中心，支持多环境配置管理。
e.配置源示例
---
// 配置源实现示例
package sources
import (
"bytes"
"context"
"io/ioutil"
"os"
"path/filepath"
"time"
"github.com/fsnotify/fsnotify"
yaml "gopkg.in/yaml.v2"
)
// 文件配置源
type FileConfigSource struct {
path string
encoding string
watcher *fsnotify.Watcher
lastMod time.Time
mutex sync.Mutex
}
// 创建文件配置源
func NewFileConfigSource(path, encoding string) (*FileConfigSource, error) {
if _, err := os.Stat(path); os.IsNotExist(err) {
return nil, fmt.Errorf("配置文件不存在: %s", path)
}
watcher, err := fsnotify.NewWatcher()
if err != nil {
return nil, fmt.Errorf("创建文件监听器失败: %s", err.Error())
}
source := &FileConfigSource{
path: path,
encoding: encoding,
watcher: watcher,
}
// 获取文件修改时间
if info, err := os.Stat(path); err == nil {
source.lastMod = info.ModTime()
}
// 监听文件所在目录
dir := filepath.Dir(path)
if err := watcher.Add(dir); err != nil {
watcher.Close()
return nil, fmt.Errorf("监听目录失败: %s", err.Error())
}
return source, nil
}
// 加载配置
func (fs *FileConfigSource) Load() ([]byte, error) {
fs.mutex.Lock()
defer fs.mutex.Unlock()
data, err := ioutil.ReadFile(fs.path)
if err != nil {
return nil, fmt.Errorf("读取配置文件失败: %s", err.Error())
}
// 根据编码格式转换
if fs.encoding == "base64" {
decoded, err := base64.StdEncoding.DecodeString(string(data))
if err != nil {
return nil, fmt.Errorf("base64解码失败: %s", err.Error())
}
return decoded, nil
}
return data, nil
}
// 监听配置变更
func (fs *FileConfigSource) Watch() (<-chan []byte, error) {
ch := make(chan []byte, 1)
go func() {
defer close(ch)
defer fs.watcher.Close()
for {
select {
case event := <-fs.watcher.Events:
if event.Name == fs.path && (event.Op&fsnotify.Write == fsnotify.Write) {
// 检查文件修改时间，避免重复触发
if info, err := os.Stat(fs.path); err == nil {
if info.ModTime().After(fs.lastMod) {
fs.lastMod = info.ModTime()
if data, err := fs.Load(); err == nil {
ch <- data
}
}
}
}
case err := <-fs.watcher.Errors:
log.Printf("文件监听错误: %s", err.Error())
}
}
}()
return ch, nil
}
// 关闭配置源
func (fs *FileConfigSource) Close() error {
return fs.watcher.Close()
}
// 获取源信息
func (fs *FileConfigSource) Info() SourceInfo {
return SourceInfo{
Type: "file",
Path: fs.path,
Encoding: fs.encoding,
Metadata: map[string]string{
"filename": filepath.Base(fs.path),
"ext": filepath.Ext(fs.path),
},
}
}
// 环境变量配置源
type EnvConfigSource struct {
prefix string
mappings map[string]string
}
// 创建环境变量配置源
func NewEnvConfigSource(prefix string, mappings map[string]string) *EnvConfigSource {
return &EnvConfigSource{
prefix: prefix,
mappings: mappings,
}
}
// 加载配置
func (es *EnvConfigSource) Load() ([]byte, error) {
config := make(map[string]interface{})
for _, env := range os.Environ() {
parts := strings.SplitN(env, "=", 2)
if len(parts) != 2 {
continue
}
key := parts[0]
value := parts[1]
// 检查前缀
if es.prefix != "" && !strings.HasPrefix(key, es.prefix) {
continue
}
// 映射键名
configKey := key
if mapping, exists := es.mappings[key]; exists {
configKey = mapping
} else {
// 转换环境变量命名到配置命名
configKey = strings.TrimPrefix(key, es.prefix)
configKey = strings.ToLower(configKey)
configKey = strings.ReplaceAll(configKey, "_", ".")
}
// 尝试类型转换
if intVal, err := strconv.Atoi(value); err == nil {
config[configKey] = intVal
} else if boolVal, err := strconv.ParseBool(value); err == nil {
config[configKey] = boolVal
} else if floatVal, err := strconv.ParseFloat(value, 64); err == nil {
config[configKey] = floatVal
} else {
config[configKey] = value
}
}
return yaml.Marshal(config)
}
// 监听配置变更
func (es *EnvConfigSource) Watch() (<-chan []byte, error) {
// 环境变量通常不支持实时监听
// 这里可以返回nil或者定期检查
return nil, nil
}
// 关闭配置源
func (es *EnvConfigSource) Close() error {
return nil
}
// 获取源信息
func (es *EnvConfigSource) Info() SourceInfo {
return SourceInfo{
Type: "env",
Path: "",
Encoding: "yaml",
Metadata: map[string]string{
"prefix": es.prefix,
},
}
}
// Consul配置源
type ConsulConfigSource struct {
client *consul.Client
prefix string
keys []string
lastData map[string][]byte
mutex sync.RWMutex
}
// 创建Consul配置源
func NewConsulConfigSource(address, prefix string, keys []string) (*ConsulConfigSource, error) {
config := consul.DefaultConfig()
config.Address = address
client, err := consul.NewClient(config)
if err != nil {
return nil, fmt.Errorf("创建Consul客户端失败: %s", err.Error())
}
return &ConsulConfigSource{
client: client,
prefix: prefix,
keys: keys,
lastData: make(map[string][]byte),
}, nil
}
// 加载配置
func (cs *ConsulConfigSource) Load() ([]byte, error) {
config := make(map[string]interface{})
cs.mutex.Lock()
defer cs.mutex.Unlock()
for _, key := range cs.keys {
fullKey := cs.prefix + key
kv, _, err := cs.client.KV().Get(fullKey, nil)
if err != nil {
return nil, fmt.Errorf("从Consul获取配置失败: %s", err.Error())
}
if kv != nil {
var value interface{}
if err := yaml.Unmarshal(kv.Value, &value); err != nil {
value = string(kv.Value)
}
config[key] = value
cs.lastData[fullKey] = kv.Value
}
}
return yaml.Marshal(config)
}
// 监听配置变更
func (cs *ConsulConfigSource) Watch() (<-chan []byte, error) {
ch := make(chan []byte, 1)
go func() {
defer close(ch)
ticker := time.NewTicker(5 * time.Second)
defer ticker.Stop()
for {
select {
case <-ticker.C:
currentData := make(map[string][]byte)
for _, key := range cs.keys {
fullKey := cs.prefix + key
kv, _, err := cs.client.KV().Get(fullKey, nil)
if err != nil {
continue
}
if kv != nil {
currentData[fullKey] = kv.Value
}
}
// 检查是否有变更
if !cs.dataEqual(currentData, cs.lastData) {
cs.mutex.Lock()
cs.lastData = currentData
cs.mutex.Unlock()
if data, err := cs.Load(); err == nil {
ch <- data
}
}
}
}
}()
return ch, nil
}
// 比较数据是否相等
func (cs *ConsulConfigSource) dataEqual(a, b map[string][]byte) bool {
if len(a) != len(b) {
return false
}
for k, v := range a {
if b[k] == nil || !bytes.Equal(v, b[k]) {
return false
}
}
return true
}
// 关闭配置源
func (cs *ConsulConfigSource) Close() error {
return nil
}
// 获取源信息
func (cs *ConsulConfigSource) Info() SourceInfo {
return SourceInfo{
Type: "consul",
Path: cs.prefix,
Encoding: "yaml",
Metadata: map[string]string{
"keys": strings.Join(cs.keys, ","),
},
}
}
---
03.配置解析器实现
a.YAML解析器
a.语法支持
完整支持YAML 1.2标准语法，包括复杂数据结构。
b.类型映射
将YAML数据类型正确映射到Go语言类型。
c.错误处理
提供详细的YAML解析错误信息。
b.JSON解析器
a.标准JSON支持
符合JSON RFC标准的解析和生成。
b.格式化输出
支持美化JSON输出，提高可读性。
c.TOML解析器
a.TOML语法
支持TOML配置文件格式的解析。
b.配置验证
提供TOML格式的配置验证机制。
d.配置解析器示例
---
// 配置解析器实现示例
package parsers
import (
"bytes"
"encoding/json"
"fmt"
"github.com/BurntSushi/toml"
yaml "gopkg.in/yaml.v2"
)
// YAML解析器
type YAMLParser struct{}
// 创建YAML解析器
func NewYAMLParser() *YAMLParser {
return &YAMLParser{}
}
// 解析YAML
func (p *YAMLParser) Parse(data []byte, v interface{}) error {
return yaml.Unmarshal(data, v)
}
// 格式化YAML
func (p *YAMLParser) Format(v interface{}) ([]byte, error) {
return yaml.Marshal(v)
}
// 支持的格式
func (p *YAMLParser) Formats() []string {
return []string{"yaml", "yml"}
}
// JSON解析器
type JSONParser struct {
pretty bool
}
// 创建JSON解析器
func NewJSONParser(pretty bool) *JSONParser {
return &JSONParser{pretty: pretty}
}
// 解析JSON
func (p *JSONParser) Parse(data []byte, v interface{}) error {
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.UseNumber()
return decoder.Decode(v)
}
// 格式化JSON
func (p *JSONParser) Format(v interface{}) ([]byte, error) {
if p.pretty {
return json.MarshalIndent(v, "", " ")
}
return json.Marshal(v)
}
// 支持的格式
func (p *JSONParser) Formats() []string {
return []string{"json"}
}
// TOML解析器
type TOMLParser struct{}
// 创建TOML解析器
func NewTOMLParser() *TOMLParser {
return &TOMLParser{}
}
// 解析TOML
func (p *TOMLParser) Parse(data []byte, v interface{}) error {
_, err := toml.Decode(string(data), v)
return err
}
// 格式化TOML
func (p *TOMLParser) Format(v interface{}) ([]byte, error) {
buf := new(bytes.Buffer)
encoder := toml.NewEncoder(buf)
err := encoder.Encode(v)
return buf.Bytes(), err
}
// 支持的格式
func (p *TOMLParser) Formats() []string {
return []string{"toml"}
}
// 解析器工厂
type ParserFactory struct{}
// 创建解析器
func (f *ParserFactory) CreateParser(format string) (ConfigParser, error) {
switch strings.ToLower(format) {
case "yaml", "yml":
return NewYAMLParser(), nil
case "json":
return NewJSONParser(false), nil
case "toml":
return NewTOMLParser(), nil
default:
return nil, fmt.Errorf("不支持的配置格式: %s", format)
}
}
// 自动检测格式
func (f *ParserFactory) AutoDetectFormat(data []byte) string {
// 尝试解析为JSON
var jsonTest interface{}
if json.Unmarshal(data, &jsonTest) == nil {
return "json"
}
// 尝试解析为YAML
var yamlTest interface{}
if yaml.Unmarshal(data, &yamlTest) == nil {
return "yaml"
}
// 尝试解析为TOML
var tomlTest interface{}
if toml.Decode(string(data), &tomlTest) == nil {
return "toml"
}
return ""
}
---
04.配置热更新机制
a.监听机制
a.文件监听
使用fsnotify监听配置文件变更。
b.配置中心监听
监听配置中心的配置变更事件。
c.定期轮询
对于不支持实时监听的配置源，采用定期轮询检查。
b.更新策略
a.原子更新
确保配置更新的原子性，避免配置不一致。
b.回滚机制
当新配置验证失败时，自动回滚到之前的配置。
c.更新通知
配置更新完成后，通知相关的组件和服务。
c.配置验证
a.语法验证
验证配置文件的语法正确性。
b.语义验证
验证配置内容的业务逻辑正确性。
c.依赖验证
验证配置项之间的依赖关系。
d.热更新示例
---
// 配置热更新机制示例
package hotreload
import (
"context"
"sync"
"time"
)
// 热更新管理器
type HotReloadManager struct {
configManager *ConfigManager
validators []ConfigValidator
rollbackStack []*ConfigSnapshot
maxRollback int
mutex sync.RWMutex
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
updateChannel chan ConfigUpdateEvent
}
// 配置验证器
type ConfigValidator interface {
Validate(oldConfig, newConfig map[string]interface{}) error
}
// 配置快照
type ConfigSnapshot struct {
Data map[string]interface{} `json:"data"`
Timestamp time.Time `json:"timestamp"`
Version int `json:"version"`
Source string `json:"source"`
}
// 配置更新事件
type ConfigUpdateEvent struct {
Key string `json:"key"`
OldValue interface{} `json:"old_value"`
NewValue interface{} `json:"new_value"`
Source string `json:"source"`
Timestamp time.Time `json:"timestamp"`
}
// 创建热更新管理器
func NewHotReloadManager(configManager *ConfigManager, maxRollback int) *HotReloadManager {
ctx, cancel := context.WithCancel(context.Background())
return &HotReloadManager{
configManager: configManager,
validators: make([]ConfigValidator, 0),
rollbackStack: make([]*ConfigSnapshot, 0, maxRollback),
maxRollback: maxRollback,
ctx: ctx,
cancel: cancel,
updateChannel: make(chan ConfigUpdateEvent, 100),
}
}
// 添加验证器
func (h *HotReloadManager) AddValidator(validator ConfigValidator) {
h.mutex.Lock()
defer h.mutex.Unlock()
h.validators = append(h.validators, validator)
}
// 开始热更新监听
func (h *HotReloadManager) Start() error {
h.wg.Add(1)
go h.watchConfigUpdates()
return nil
}
// 监听配置更新
func (h *HotReloadManager) watchConfigUpdates() {
defer h.wg.Done()
for {
select {
case event := <-h.updateChannel:
h.processConfigUpdate(event)
case <-h.ctx.Done():
return
}
}
}
// 处理配置更新
func (h *HotReloadManager) processConfigUpdate(event ConfigUpdateEvent) {
h.mutex.Lock()
defer h.mutex.Unlock()
// 创建当前配置快照
currentConfig := h.configManager.GetCurrentConfig()
snapshot := &ConfigSnapshot{
Data: currentConfig,
Timestamp: time.Now(),
Version: len(h.rollbackStack) + 1,
Source: event.Source,
}
// 添加到回滚栈
h.rollbackStack = append(h.rollbackStack, snapshot)
if len(h.rollbackStack) > h.maxRollback {
h.rollbackStack = h.rollbackStack[1:]
}
// 执行更新
if err := h.applyConfigUpdate(event); err != nil {
log.Printf("应用配置更新失败: %s", err.Error())
h.rollbackToSnapshot(len(h.rollbackStack) - 2)
return
}
// 验证新配置
newConfig := h.configManager.GetCurrentConfig()
for _, validator := range h.validators {
if err := validator.Validate(currentConfig, newConfig); err != nil {
log.Printf("配置验证失败: %s", err.Error())
h.rollbackToSnapshot(len(h.rollbackStack) - 2)
return
}
}
log.Printf("配置更新成功: %s", event.Key)
}
// 应用配置更新
func (h *HotReloadManager) applyConfigUpdate(event ConfigUpdateEvent) error {
return h.configManager.UpdateConfig(event.Key, event.NewValue)
}
// 回滚到指定快照
func (h *HotReloadManager) rollbackToSnapshot(index int) error {
if index < 0 || index >= len(h.rollbackStack) {
return fmt.Errorf("无效的快照索引: %d", index)
}
snapshot := h.rollbackStack[index]
return h.configManager.LoadSnapshot(snapshot)
}
// 回滚到上一个版本
func (h *HotReloadManager) Rollback() error {
h.mutex.Lock()
defer h.mutex.Unlock()
if len(h.rollbackStack) < 2 {
return fmt.Errorf("没有可回滚的配置版本")
}
return h.rollbackToSnapshot(len(h.rollbackStack) - 2)
}
// 获取回滚历史
func (h *HotReloadManager) GetRollbackHistory() []*ConfigSnapshot {
h.mutex.RLock()
defer h.mutex.RUnlock()
history := make([]*ConfigSnapshot, len(h.rollbackStack))
copy(history, h.rollbackStack)
return history
}
// 关闭热更新管理器
func (h *HotReloadManager) Close() error {
h.cancel()
h.wg.Wait()
close(h.updateChannel)
return nil
}
// 配置验证器示例
type DatabaseConfigValidator struct{}
// 验证数据库配置
func (v *DatabaseConfigValidator) Validate(oldConfig, newConfig map[string]interface{}) error {
// 检查必要的数据库配置项
requiredKeys := []string{"database.host", "database.port", "database.name"}
for _, key := range requiredKeys {
if _, exists := newConfig[key]; !exists {
return fmt.Errorf("缺少必要的数据库配置项: %s", key)
}
}
// 验证端口范围
if port, exists := newConfig["database.port"]; exists {
if portNum, ok := port.(int); ok {
if portNum < 1 || portNum > 65535 {
return fmt.Errorf("数据库端口无效: %d", portNum)
}
}
}
// 验证连接池配置
if maxConns, exists := newConfig["database.max_connections"]; exists {
if maxConnsNum, ok := maxConns.(int); ok {
if maxConnsNum <= 0 {
return fmt.Errorf("最大连接数必须大于0")
}
}
}
return nil
}
// 服务配置验证器
type ServiceConfigValidator struct{}
// 验证服务配置
func (v *ServiceConfigValidator) Validate(oldConfig, newConfig map[string]interface{}) error {
// 检查服务地址变更
oldAddr := oldConfig["service.address"]
newAddr := newConfig["service.address"]
if oldAddr != newAddr && newAddr != nil {
log.Printf("服务地址变更: %s -> %s", oldAddr, newAddr)
}
// 检查端口变更
oldPort := oldConfig["service.port"]
newPort := newConfig["service.port"]
if oldPort != newPort && newPort != nil {
if portNum, ok := newPort.(int); ok {
if portNum < 1024 || portNum > 65535 {
return fmt.Errorf("服务端口无效: %d", portNum)
}
}
}
return nil
}
---
2.5 日志系统组件 Logging
01.日志系统架构设计
a.分层架构设计
a.日志接口层
定义统一的日志记录接口，支持多种日志实现。
b.日志适配器层
提供不同日志库的适配器，支持zap、logrus、zerolog等。
c.日志输出层
支持多种输出目标，包括文件、控制台、远程服务等。
d.日志格式化层
提供多种日志格式化器，支持JSON、Text、Structured等格式。
b.核心接口设计
a.Logger接口
定义日志记录器的基本操作接口。
b.Level接口
定义日志级别管理接口。
c.Formatter接口
定义日志格式化接口。
d.Writer接口
定义日志输出接口。
c.日志系统示例
---
// Logging日志系统架构示例
package logging
import (
"context"
"fmt"
"io"
"os"
"runtime"
"sync"
"time"
"github.com/go-kratos/kratos/v2/log"
)
// 日志级别
type Level int32
const (
LevelDebug Level = iota
LevelInfo
LevelWarn
LevelError
LevelFatal
LevelPanic
)
// 日志级别字符串
var LevelNames = map[Level]string{
LevelDebug: "DEBUG",
LevelInfo: "INFO",
LevelWarn: "WARN",
LevelError: "ERROR",
LevelFatal: "FATAL",
LevelPanic: "PANIC",
}
// 日志记录接口
type Logger interface {
// 记录调试日志
Debug(ctx context.Context, args ...interface{})
// 记录信息日志
Info(ctx context.Context, args ...interface{})
// 记录警告日志
Warn(ctx context.Context, args ...interface{})
// 记录错误日志
Error(ctx context.Context, args ...interface{})
// 记录致命错误日志
Fatal(ctx context.Context, args ...interface{})
// 记录恐慌日志
Panic(ctx context.Context, args ...interface{})
// 格式化日志记录
Debugf(ctx context.Context, format string, args ...interface{})
Infof(ctx context.Context, format string, args ...interface{})
Warnf(ctx context.Context, format string, args ...interface{})
Errorf(ctx context.Context, format string, args ...interface{})
Fatalf(ctx context.Context, format string, args ...interface{})
Panicf(ctx context.Context, format string, args ...interface{})
// 键值对日志记录
Debugw(ctx context.Context, msg string, keysAndValues ...interface{})
Infow(ctx context.Context, msg string, keysAndValues ...interface{})
Warnw(ctx context.Context, msg string, keysAndValues ...interface{})
Errorw(ctx context.Context, msg string, keysAndValues ...interface{})
Fatalw(ctx context.Context, msg string, keysAndValues ...interface{})
Panicw(ctx context.Context, msg string, keysAndValues ...interface{})
// 获取子日志记录器
WithValues(ctx context.Context, keysAndValues ...interface{}) Logger
WithName(name string) Logger
// 设置日志级别
SetLevel(level Level)
GetLevel() Level
// 获取底层日志器
Unwrap() interface{}
}
// 日志格式化器接口
type Formatter interface {
Format(entry *LogEntry) ([]byte, error)
}
// 日志输出器接口
type Writer interface {
Write(p []byte) (n int, err error)
Sync() error
Close() error
}
// 日志条目
type LogEntry struct {
Level Level `json:"level"`
Time time.Time `json:"time"`
Message string `json:"message"`
Logger string `json:"logger,omitempty"`
Caller string `json:"caller,omitempty"`
Function string `json:"function,omitempty"`
Stack string `json:"stack,omitempty"`
Context map[string]interface{} `json:"context,omitempty"`
Fields map[string]interface{} `json:"fields,omitempty"`
}
// 结构化日志记录器实现
type StructuredLogger struct {
name string
level Level
formatter Formatter
writers []Writer
context map[string]interface{}
mutex sync.RWMutex
}
// 创建结构化日志记录器
func NewStructuredLogger(name string, level Level, formatter Formatter, writers ...Writer) *StructuredLogger {
return &StructuredLogger{
name: name,
level: level,
formatter: formatter,
writers: writers,
context: make(map[string]interface{}),
}
}
// 记录调试日志
func (l *StructuredLogger) Debug(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelDebug, fmt.Sprint(args...), nil)
}
// 记录信息日志
func (l *StructuredLogger) Info(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelInfo, fmt.Sprint(args...), nil)
}
// 记录警告日志
func (l *StructuredLogger) Warn(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelWarn, fmt.Sprint(args...), nil)
}
// 记录错误日志
func (l *StructuredLogger) Error(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelError, fmt.Sprint(args...), nil)
}
// 记录致命错误日志
func (l *StructuredLogger) Fatal(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelFatal, fmt.Sprint(args...), nil)
os.Exit(1)
}
// 记录恐慌日志
func (l *StructuredLogger) Panic(ctx context.Context, args ...interface{}) {
l.log(ctx, LevelPanic, fmt.Sprint(args...), nil)
panic(args)
}
// 格式化日志记录
func (l *StructuredLogger) Debugf(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelDebug, fmt.Sprintf(format, args...), nil)
}
func (l *StructuredLogger) Infof(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelInfo, fmt.Sprintf(format, args...), nil)
}
func (l *StructuredLogger) Warnf(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelWarn, fmt.Sprintf(format, args...), nil)
}
func (l *StructuredLogger) Errorf(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelError, fmt.Sprintf(format, args...), nil)
}
func (l *StructuredLogger) Fatalf(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelFatal, fmt.Sprintf(format, args...), nil)
os.Exit(1)
}
func (l *StructuredLogger) Panicf(ctx context.Context, format string, args ...interface{}) {
l.log(ctx, LevelPanic, fmt.Sprintf(format, args...), nil)
panic(fmt.Sprintf(format, args...))
}
// 键值对日志记录
func (l *StructuredLogger) Debugw(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelDebug, msg, keysAndValues)
}
func (l *StructuredLogger) Infow(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelInfo, msg, keysAndValues)
}
func (l *StructuredLogger) Warnw(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelWarn, msg, keysAndValues)
}
func (l *StructuredLogger) Errorw(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelError, msg, keysAndValues)
}
func (l *StructuredLogger) Fatalw(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelFatal, msg, keysAndValues)
os.Exit(1)
}
func (l *StructuredLogger) Panicw(ctx context.Context, msg string, keysAndValues ...interface{}) {
l.log(ctx, LevelPanic, msg, keysAndValues)
panic(msg)
}
// 获取带上下文的日志记录器
func (l *StructuredLogger) WithValues(ctx context.Context, keysAndValues ...interface{}) Logger {
newLogger := l.clone()
newLogger.mergeContext(keysAndValues)
return newLogger
}
// 获取带名称的日志记录器
func (l *StructuredLogger) WithName(name string) Logger {
newLogger := l.clone()
if l.name != "" {
newLogger.name = l.name + "." + name
} else {
newLogger.name = name
}
return newLogger
}
// 设置日志级别
func (l *StructuredLogger) SetLevel(level Level) {
l.mutex.Lock()
defer l.mutex.Unlock()
l.level = level
}
// 获取日志级别
func (l *StructuredLogger) GetLevel() Level {
l.mutex.RLock()
defer l.mutex.RUnlock()
return l.level
}
// 获取底层日志器
func (l *StructuredLogger) Unwrap() interface{} {
return l
}
// 记录日志
func (l *StructuredLogger) log(ctx context.Context, level Level, msg string, keysAndValues []interface{}) {
if !l.shouldLog(level) {
return
}
l.mutex.RLock()
defer l.mutex.RUnlock()
// 创建日志条目
entry := &LogEntry{
Level: level,
Time: time.Now(),
Message: msg,
Logger: l.name,
Context: l.getContextCopy(),
Fields: make(map[string]interface{}),
}
// 添加调用者信息
if pc, file, line, ok := runtime.Caller(3); ok {
entry.Caller = fmt.Sprintf("%s:%d", file, line)
if fn := runtime.FuncForPC(pc); fn != nil {
entry.Function = fn.Name()
}
}
// 添加字段
if keysAndValues != nil {
entry.Fields = l.parseFields(keysAndValues)
}
// 添加上下文信息
l.addContextFields(ctx, entry)
// 添加堆栈信息（对于错误级别）
if level >= LevelError {
entry.Stack = l.getStackTrace()
}
// 格式化并输出
l.output(entry)
}
// 检查是否应该记录日志
func (l *StructuredLogger) shouldLog(level Level) bool {
return level >= l.level
}
// 克隆日志记录器
func (l *StructuredLogger) clone() *StructuredLogger {
newLogger := &StructuredLogger{
name: l.name,
level: l.level,
formatter: l.formatter,
writers: make([]Writer, len(l.writers)),
context: make(map[string]interface{}),
}
copy(newLogger.writers, l.writers)
for k, v := range l.context {
newLogger.context[k] = v
}
return newLogger
}
// 合并上下文
func (l *StructuredLogger) mergeContext(keysAndValues []interface{}) {
if len(keysAndValues)%2 != 0 {
keysAndValues = append(keysAndValues, "MISSING_VALUE")
}
for i := 0; i < len(keysAndValues); i += 2 {
if key, ok := keysAndValues[i].(string); ok {
l.context[key] = keysAndValues[i+1]
}
}
}
// 获取上下文副本
func (l *StructuredLogger) getContextCopy() map[string]interface{} {
copy := make(map[string]interface{})
for k, v := range l.context {
copy[k] = v
}
return copy
}
// 解析字段
func (l *StructuredLogger) parseFields(keysAndValues []interface{}) map[string]interface{} {
fields := make(map[string]interface{})
if len(keysAndValues)%2 != 0 {
keysAndValues = append(keysAndValues, "MISSING_VALUE")
}
for i := 0; i < len(keysAndValues); i += 2 {
if key, ok := keysAndValues[i].(string); ok {
fields[key] = keysAndValues[i+1]
}
}
return fields
}
// 添加上下文字段
func (l *StructuredLogger) addContextFields(ctx context.Context, entry *LogEntry) {
// 添加请求ID
if requestID := ctx.Value("request_id"); requestID != nil {
entry.Context["request_id"] = requestID
}
// 添加用户ID
if userID := ctx.Value("user_id"); userID != nil {
entry.Context["user_id"] = userID
}
// 添加链路追踪ID
if traceID := ctx.Value("trace_id"); traceID != nil {
entry.Context["trace_id"] = traceID
}
}
// 获取堆栈信息
func (l *StructuredLogger) getStackTrace() string {
buf := make([]byte, 1024)
for {
n := runtime.Stack(buf, false)
if n < len(buf) {
return string(buf[:n])
}
buf = make([]byte, 2*len(buf))
}
}
// 输出日志
func (l *StructuredLogger) output(entry *LogEntry) {
data, err := l.formatter.Format(entry)
if err != nil {
// 格式化失败时的处理
data = []byte(fmt.Sprintf("日志格式化失败: %s, 原始消息: %s", err.Error(), entry.Message))
}
for _, writer := range l.writers {
if _, err := writer.Write(data); err != nil {
// 输出失败时的处理
fmt.Fprintf(os.Stderr, "日志输出失败: %s\n", err.Error())
}
}
}
---
02.日志格式化器实现
a.JSON格式化器
a.结构化输出
将日志以JSON格式输出，便于机器解析和分析。
b.字段映射
标准化日志字段名称，提高兼容性。
c.时间格式
支持多种时间格式输出，包括ISO8601、Unix时间戳等。
b.Text格式化器
a.人类可读
提供易于人类阅读的文本格式日志。
b.彩色输出
支持彩色输出，提高日志可读性。
c.时间格式化
支持自定义时间格式显示。
c.Structured格式化器
a.键值对格式
以键值对形式输出结构化日志。
b.字段过滤
支持字段过滤和重命名。
c.嵌套结构
支持嵌套结构的日志输出。
d.格式化器示例
---
// 日志格式化器实现示例
package formatters
import (
"encoding/json"
"fmt"
"sort"
"strings"
"time"
)
// JSON格式化器
type JSONFormatter struct {
TimestampFormat string `json:"timestamp_format"`
PrettyPrint bool `json:"pretty_print"`
DisableColors bool `json:"disable_colors"`
}
// 创建JSON格式化器
func NewJSONFormatter(timestampFormat string, prettyPrint bool) *JSONFormatter {
if timestampFormat == "" {
timestampFormat = time.RFC3339
}
return &JSONFormatter{
TimestampFormat: timestampFormat,
PrettyPrint: prettyPrint,
}
}
// 格式化日志条目
func (f *JSONFormatter) Format(entry *LogEntry) ([]byte, error) {
// 创建格式化后的条目
formattedEntry := map[string]interface{}{
"level": LevelNames[entry.Level],
"time": entry.Time.Format(f.TimestampFormat),
"message": entry.Message,
}
// 添加可选字段
if entry.Logger != "" {
formattedEntry["logger"] = entry.Logger
}
if entry.Caller != "" {
formattedEntry["caller"] = entry.Caller
}
if entry.Function != "" {
formattedEntry["function"] = entry.Function
}
if entry.Context != nil && len(entry.Context) > 0 {
formattedEntry["context"] = entry.Context
}
if entry.Fields != nil && len(entry.Fields) > 0 {
formattedEntry["fields"] = entry.Fields
}
if entry.Stack != "" {
formattedEntry["stack"] = entry.Stack
}
// 序列化为JSON
var data []byte
var err error
if f.PrettyPrint {
data, err = json.MarshalIndent(formattedEntry, "", " ")
data = append(data, '\n')
} else {
data, err = json.Marshal(formattedEntry)
data = append(data, '\n')
}
return data, err
}
// Text格式化器
type TextFormatter struct {
TimestampFormat string `json:"timestamp_format"`
DisableColors bool `json:"disable_colors"`
FullCaller bool `json:"full_caller"`
EnableQuote bool `json:"enable_quote"`
}
// 颜色代码
const (
ColorReset = "\033[0m"
ColorRed = "\033[31m"
ColorYellow = "\033[33m"
ColorBlue = "\033[34m"
ColorGray = "\033[37m"
ColorWhite = "\033[97m"
)
// 日志级别颜色映射
var LevelColors = map[Level]string{
LevelDebug: ColorBlue,
LevelInfo: ColorWhite,
LevelWarn: ColorYellow,
LevelError: ColorRed,
LevelFatal: ColorRed,
LevelPanic: ColorRed,
}
// 创建Text格式化器
func NewTextFormatter(timestampFormat string, disableColors bool) *TextFormatter {
if timestampFormat == "" {
timestampFormat = "2006-01-02 15:04:05"
}
return &TextFormatter{
TimestampFormat: timestampFormat,
DisableColors: disableColors,
}
}
// 格式化日志条目
func (f *TextFormatter) Format(entry *LogEntry) ([]byte, error) {
var builder strings.Builder
// 时间戳
builder.WriteString(entry.Time.Format(f.TimestampFormat))
builder.WriteString(" ")
// 日志级别（带颜色）
levelStr := fmt.Sprintf("[%s]", LevelNames[entry.Level])
if !f.DisableColors {
if color, exists := LevelColors[entry.Level]; exists {
builder.WriteString(color)
builder.WriteString(levelStr)
builder.WriteString(ColorReset)
} else {
builder.WriteString(levelStr)
}
} else {
builder.WriteString(levelStr)
}
builder.WriteString(" ")
// 日志器名称
if entry.Logger != "" {
builder.WriteString(fmt.Sprintf("[%s] ", entry.Logger))
}
// 消息
if f.EnableQuote {
builder.WriteString(fmt.Sprintf("%q", entry.Message))
} else {
builder.WriteString(entry.Message)
}
// 调用者信息
if entry.Caller != "" {
caller := entry.Caller
if !f.FullCaller {
// 只显示文件名和行号
parts := strings.Split(entry.Caller, "/")
caller = parts[len(parts)-1]
}
builder.WriteString(fmt.Sprintf " [%s]", caller))
}
// 上下文字段
if entry.Context != nil && len(entry.Context) > 0 {
builder.WriteString(" [")
first := true
for k, v := range entry.Context {
if !first {
builder.WriteString(", ")
}
builder.WriteString(fmt.Sprintf("%s=%v", k, v))
first = false
}
builder.WriteString("]")
}
// 额外字段
if entry.Fields != nil && len(entry.Fields) > 0 {
builder.WriteString(" {")
first := true
keys := make([]string, 0, len(entry.Fields))
for k := range entry.Fields {
keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
if !first {
builder.WriteString(", ")
}
builder.WriteString(fmt.Sprintf("%s=%v", k, entry.Fields[k]))
first = false
}
builder.WriteString("}")
}
// 堆栈信息
if entry.Stack != "" {
builder.WriteString("\n")
builder.WriteString(entry.Stack)
}
builder.WriteString("\n")
return []byte(builder.String()), nil
}
// Structured格式化器
type StructuredFormatter struct {
TimestampFormat string `json:"timestamp_format"`
DisableColors bool `json:"disable_colors"`
FieldSeparator string `json:"field_separator"`
KeyValueFormat string `json:"key_value_format"`
SortFields bool `json:"sort_fields"`
ExcludeFields []string `json:"exclude_fields"`
}
// 创建Structured格式化器
func NewStructuredFormatter(timestampFormat string, fieldSeparator string) *StructuredFormatter {
if timestampFormat == "" {
timestampFormat = "2006-01-02T15:04:05.000Z"
}
if fieldSeparator == "" {
fieldSeparator = " "
}
return &StructuredFormatter{
TimestampFormat: timestampFormat,
FieldSeparator: fieldSeparator,
KeyValueFormat: "%s=%v",
SortFields: true,
}
}
// 格式化日志条目
func (f *StructuredFormatter) Format(entry *LogEntry) ([]byte, error) {
var fields []string
// 添加时间戳
fields = append(fields, fmt.Sprintf("time=%s", entry.Time.Format(f.TimestampFormat)))
// 添加日志级别
fields = append(fields, fmt.Sprintf("level=%s", LevelNames[entry.Level]))
// 添加日志器名称
if entry.Logger != "" {
fields = append(fields, fmt.Sprintf("logger=%s", entry.Logger))
}
// 添加消息
fields = append(fields, fmt.Sprintf("msg=%s", entry.Message))
// 添加调用者信息
if entry.Caller != "" {
fields = append(fields, fmt.Sprintf("caller=%s", entry.Caller))
}
// 添加上下文字段
if entry.Context != nil && len(entry.Context) > 0 {
for k, v := range entry.Context {
if !f.shouldExcludeField(k) {
fields = append(fields, fmt.Sprintf(f.KeyValueFormat, "ctx."+k, v))
}
}
}
// 添加额外字段
if entry.Fields != nil && len(entry.Fields) > 0 {
keys := make([]string, 0, len(entry.Fields))
for k := range entry.Fields {
if !f.shouldExcludeField(k) {
keys = append(keys, k)
}
}
if f.SortFields {
sort.Strings(keys)
}
for _, k := range keys {
fields = append(fields, fmt.Sprintf(f.KeyValueFormat, k, entry.Fields[k]))
}
}
// 添加堆栈信息
if entry.Stack != "" {
fields = append(fields, fmt.Sprintf("stack=%s", entry.Stack))
}
// 组合所有字段
result := strings.Join(fields, f.FieldSeparator) + "\n"
return []byte(result), nil
}
// 检查是否应该排除字段
func (f *StructuredFormatter) shouldExcludeField(fieldName string) bool {
for _, exclude := range f.ExcludeFields {
if fieldName == exclude {
return true
}
}
return false
}
---
03.日志输出器实现
a.文件输出器
a.文件轮转
支持按时间、大小进行日志文件轮转。
b.文件压缩
支持历史日志文件的自动压缩。
c.异步写入
提供异步文件写入，提高性能。
b.控制台输出器
a.标准输出
将日志输出到标准输出流。
b.错误输出
将错误级别日志输出到标准错误流。
c.彩色显示
支持控制台彩色输出。
c.远程日志输出器
a.ELK Stack集成
支持将日志发送到Elasticsearch。
b.云日志服务
支持AWS CloudWatch、阿里云日志服务等。
c.日志聚合
支持分布式日志聚合和收集。
d.输出器示例
---
// 日志输出器实现示例
package writers
import (
"bufio"
"compress/gzip"
"fmt"
"io"
"os"
"path/filepath"
"sync"
"time"
"go.uber.org/multierr"
)
// 文件输出器配置
type FileWriterConfig struct {
Filename string `json:"filename"`
MaxSize int64 `json:"max_size"` // MB
MaxBackups int `json:"max_backups"`
MaxAge time.Duration `json:"max_age"`
Compress bool `json:"compress"`
LocalTime bool `json:"local_time"`
BufferSize int `json:"buffer_size"`
FlushInterval time.Duration `json:"flush_interval"`
Async bool `json:"async"`
ChannelSize int `json:"channel_size"`
}
// 文件输出器
type FileWriter struct {
config *FileWriterConfig
file *os.File
size int64
mutex sync.Mutex
buffer *bufio.Writer
flushTimer *time.Timer
asyncWriter *AsyncFileWriter
closed bool
}
// 创建文件输出器
func NewFileWriter(config *FileWriterConfig) (*FileWriter, error) {
if config.Filename == "" {
return nil, fmt.Errorf("文件名不能为空")
}
// 设置默认值
if config.MaxSize <= 0 {
config.MaxSize = 100 // 100MB
}
if config.MaxBackups <= 0 {
config.MaxBackups = 10
}
if config.BufferSize <= 0 {
config.BufferSize = 64 * 1024 // 64KB
}
if config.FlushInterval <= 0 {
config.FlushInterval = 5 * time.Second
}
if config.ChannelSize <= 0 {
config.ChannelSize = 10000
}
writer := &FileWriter{
config: config,
}
if err := writer.openFile(); err != nil {
return nil, err
}
if config.Async {
writer.asyncWriter = NewAsyncFileWriter(writer.file, config.ChannelSize)
} else {
writer.buffer = bufio.NewWriterSize(writer.file, config.BufferSize)
writer.startFlushTimer()
}
return writer, nil
}
// 打开文件
func (w *FileWriter) openFile() error {
// 确保目录存在
dir := filepath.Dir(w.config.Filename)
if err := os.MkdirAll(dir, 0755); err != nil {
return fmt.Errorf("创建目录失败: %s", err.Error())
}
// 打开或创建文件
file, err := os.OpenFile(w.config.Filename, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0644)
if err != nil {
return fmt.Errorf("打开文件失败: %s", err.Error())
}
// 获取文件大小
info, err := file.Stat()
if err != nil {
file.Close()
return fmt.Errorf("获取文件信息失败: %s", err.Error())
}
w.file = file
w.size = info.Size()
return nil
}
// 写入数据
func (w *FileWriter) Write(p []byte) (n int, err error) {
w.mutex.Lock()
defer w.mutex.Unlock()
if w.closed {
return 0, fmt.Errorf("文件输出器已关闭")
}
if w.config.Async {
return w.asyncWriter.Write(p)
}
n, err = w.buffer.Write(p)
w.size += int64(n)
// 检查是否需要轮转
if w.size >= w.config.MaxSize*1024*1024 {
if err := w.rotate(); err != nil {
return n, err
}
}
return n, err
}
// 同步数据
func (w *FileWriter) Sync() error {
w.mutex.Lock()
defer w.mutex.Unlock()
if w.closed {
return nil
}
if w.config.Async {
return w.asyncWriter.Sync()
}
return multierr.Combine(
w.buffer.Flush(),
w.file.Sync(),
)
}
// 关闭输出器
func (w *FileWriter) Close() error {
w.mutex.Lock()
defer w.mutex.Unlock()
if w.closed {
return nil
}
w.closed = true
var errs []error
if w.config.Async {
errs = append(errs, w.asyncWriter.Close())
} else {
if w.flushTimer != nil {
w.flushTimer.Stop()
}
errs = append(errs, w.buffer.Flush())
}
errs = append(errs, w.file.Close())
return multierr.Combine(errs...)
}
// 轮转文件
func (w *FileWriter) rotate() error {
// 关闭当前文件
if err := w.buffer.Flush(); err != nil {
return fmt.Errorf("刷新缓冲区失败: %s", err.Error())
}
if err := w.file.Close(); err != nil {
return fmt.Errorf("关闭当前文件失败: %s", err.Error())
}
// 生成备份文件名
backupName := w.generateBackupName()
// 重命名当前文件
if err := os.Rename(w.config.Filename, backupName); err != nil {
return fmt.Errorf("重命名文件失败: %s", err.Error())
}
// 压缩备份文件
if w.config.Compress {
go w.compressFile(backupName)
}
// 清理旧备份
go w.cleanupOldBackups()
// 打开新文件
return w.openFile()
}
// 生成备份文件名
func (w *FileWriter) generateBackupName() string {
timestamp := time.Now()
if !w.config.LocalTime {
timestamp = timestamp.UTC()
}
return fmt.Sprintf("%s.%s", w.config.Filename, timestamp.Format("2006-01-02T15-04-05"))
}
// 压缩文件
func (w *FileWriter) compressFile(filename string) {
// 打开源文件
src, err := os.Open(filename)
if err != nil {
log.Printf("打开文件进行压缩失败: %s", err.Error())
return
}
defer src.Close()
// 创建压缩文件
gzipFile, err := os.Create(filename + ".gz")
if err != nil {
log.Printf("创建压缩文件失败: %s", err.Error())
return
}
defer gzipFile.Close()
// 创建gzip写入器
gzipWriter := gzip.NewWriter(gzipFile)
defer gzipWriter.Close()
// 复制数据
if _, err := io.Copy(gzipWriter, src); err != nil {
log.Printf("压缩文件失败: %s", err.Error())
return
}
// 删除原始文件
if err := os.Remove(filename); err != nil {
log.Printf("删除原始文件失败: %s", err.Error())
}
}
// 清理旧备份
func (w *FileWriter) cleanupOldBackups() {
pattern := w.config.Filename + ".*"
matches, err := filepath.Glob(pattern)
if err != nil {
log.Printf("查找备份文件失败: %s", err.Error())
return
}
// 按修改时间排序
type fileInfo struct {
path string
}
files := make([]fileInfo, 0, len(matches))
for _, match := range matches {
if match == w.config.Filename {
continue
}
info, err := os.Stat(match)
if err != nil {
continue
}
files = append(files, fileInfo{
path: match,
})
}
// 删除超过限制的备份
if len(files) > w.config.MaxBackups {
// 这里应该按时间排序，简化处理
for i := 0; i < len(files)-w.config.MaxBackups; i++ {
if err := os.Remove(files[i].path); err != nil {
log.Printf("删除旧备份失败: %s", err.Error())
}
}
}
}
// 启动刷新定时器
func (w *FileWriter) startFlushTimer() {
w.flushTimer = time.AfterFunc(w.config.FlushInterval, func() {
w.mutex.Lock()
defer w.mutex.Unlock()
if !w.closed {
w.buffer.Flush()
w.startFlushTimer()
}
})
}
// 异步文件写入器
type AsyncFileWriter struct {
file *os.File
channel chan []byte
done chan struct{}
wg sync.WaitGroup
mu sync.Mutex
closed bool
}
// 创建异步文件写入器
func NewAsyncFileWriter(file *os.File, channelSize int) *AsyncFileWriter {
writer := &AsyncFileWriter{
file: file,
channel: make(chan []byte, channelSize),
done: make(chan struct{}),
}
writer.wg.Add(1)
go writer.writeLoop()
return writer
}
// 写入数据到通道
func (w *AsyncFileWriter) Write(p []byte) (n int, err error) {
data := make([]byte, len(p))
copy(data, p)
select {
case w.channel <- data:
return len(p), nil
default:
// 通道满，直接写入
return w.file.Write(p)
}
}
// 同步数据
func (w *AsyncFileWriter) Sync() error {
return w.file.Sync()
}
// 关闭写入器
func (w *AsyncFileWriter) Close() error {
w.mu.Lock()
defer w.mu.Unlock()
if w.closed {
return nil
}
w.closed = true
close(w.channel)
w.wg.Wait()
return w.file.Close()
}
// 写入循环
func (w *AsyncFileWriter) writeLoop() {
defer w.wg.Done()
buffer := make([][]byte, 0, 100)
flushTimer := time.NewTicker(100 * time.Millisecond)
defer flushTimer.Stop()
for {
select {
case data, ok := <-w.channel:
if !ok {
// 通道关闭，写入剩余数据
w.flushBuffer(buffer)
return
}
buffer = append(buffer, data)
// 缓冲区满，立即刷新
if len(buffer) >= cap(buffer) {
w.flushBuffer(buffer)
buffer = buffer[:0]
}
case <-flushTimer.C:
// 定时刷新
w.flushBuffer(buffer)
buffer = buffer[:0]
}
}
}
// 刷新缓冲区
func (w *AsyncFileWriter) flushBuffer(buffer [][]byte) {
for _, data := range buffer {
if _, err := w.file.Write(data); err != nil {
log.Printf("异步写入文件失败: %s", err.Error())
}
}
}
// 控制台输出器
type ConsoleWriter struct {
stdoutWriter io.Writer
stderrWriter io.Writer
levelFilter Level
}
// 创建控制台输出器
func NewConsoleWriter(levelFilter Level) *ConsoleWriter {
return &ConsoleWriter{
stdoutWriter: os.Stdout,
stderrWriter: os.Stderr,
levelFilter: levelFilter,
}
}
// 写入数据
func (w *ConsoleWriter) Write(p []byte) (n int, err error) {
// 简化处理：判断日志级别决定输出流
// 实际实现中需要从日志条目中解析级别
if strings.Contains(string(p), "[ERROR]") ||
strings.Contains(string(p), "[FATAL]") ||
strings.Contains(string(p), "[PANIC]") {
return w.stderrWriter.Write(p)
}
return w.stdoutWriter.Write(p)
}
// 同步数据
func (w *ConsoleWriter) Sync() error {
// 控制台输出通常不需要同步
return nil
}
// 关闭输出器
func (w *ConsoleWriter) Close() error {
return nil
}
---
2.6 监控系统组件 Metrics
01.监控系统架构设计
a.分层架构设计
a.指标收集层
提供多种指标的收集能力，包括计数器、仪表盘、直方图等。
b.指标聚合层
负责指标的聚合和计算，支持时间窗口聚合。
c.指标存储层
提供指标的本地缓存和持久化存储。
d.指标导出层
支持多种监控系统的指标导出格式。
b.核心接口设计
a.Metric接口
定义指标的基本操作接口。
b.Collector接口
定义指标收集器接口。
c.Registry接口
定义指标注册表接口。
d.Exporter接口
定义指标导出器接口。
c.监控系统示例
---
// Metrics监控系统架构示例
package metrics
import (
"context"
"fmt"
"math"
"sort"
"sync"
"time"
"github.com/prometheus/client_golang/prometheus"
)
// 指标类型
type MetricType int
const (
MetricTypeCounter MetricType = iota
MetricTypeGauge
MetricTypeHistogram
MetricTypeSummary
MetricTypeUntyped
)
// 指标接口
type Metric interface {
// 获取指标名称
Name() string
// 获取指标类型
Type() MetricType
// 获取指标描述
Help() string
// 获取指标标签
Labels() []string
// 收集指标数据
Collect() *MetricData
// 获取指标值
Value() float64
}
// 指标数据
type MetricData struct {
Name string `json:"name"`
Type MetricType `json:"type"`
Help string `json:"help"`
Labels []string `json:"labels"`
Values map[string]float64 `json:"values"`
Timestamp time.Time `json:"timestamp"`
Samples []Sample `json:"samples"`
}
// 样本数据
type Sample struct {
Labels map[string]string `json:"labels"`
Value float64 `json:"value"`
Timestamp time.Time `json:"timestamp"`
}
// 指标收集器
type Collector interface {
// 收集所有指标
Collect() ([]*MetricData, error)
// 注册指标
Register(metric Metric) error
// 注销指标
Unregister(name string) error
// 获取指标
GetMetric(name string) (Metric, bool)
}
// 指标注册表
type Registry interface {
// 注册收集器
Register(name string, collector Collector) error
// 注销收集器
Unregister(name string) error
// 收集所有数据
Gather() ([]*MetricData, error)
// 获取收集器
GetCollector(name string) (Collector, bool)
}
// 计数器指标
type Counter struct {
name string
help string
labels []string
value float64
mutex sync.RWMutex
labelValues map[string]*Counter
}
// 创建计数器
func NewCounter(name, help string, labels ...string) *Counter {
return &Counter{
name: name,
help: help,
labels: labels,
labelValues: make(map[string]*Counter),
}
}
// 获取指标名称
func (c *Counter) Name() string {
return c.name
}
// 获取指标类型
func (c *Counter) Type() MetricType {
return MetricTypeCounter
}
// 获取指标描述
func (c *Counter) Help() string {
return c.help
}
// 获取指标标签
func (c *Counter) Labels() []string {
return c.labels
}
// 递增计数器
func (c *Counter) Inc() {
c.Add(1)
}
// 增加指定值
func (c *Counter) Add(value float64) {
c.mutex.Lock()
defer c.mutex.Unlock()
c.value += value
}
// 带标签递增
func (c *Counter) WithLabelValues(values ...string) *Counter {
if len(values) != len(c.labels) {
return c
}
key := c.generateLabelKey(values)
c.mutex.RLock()
child, exists := c.labelValues[key]
c.mutex.RUnlock()
if !exists {
c.mutex.Lock()
// 双重检查
if child, exists = c.labelValues[key]; !exists {
child = &Counter{
name: c.name,
help: c.help,
labels: c.labels,
}
c.labelValues[key] = child
}
c.mutex.Unlock()
}
return child
}
// 获取指标值
func (c *Counter) Value() float64 {
c.mutex.RLock()
defer c.mutex.RUnlock()
return c.value
}
// 收集指标数据
func (c *Counter) Collect() *MetricData {
c.mutex.RLock()
defer c.mutex.RUnlock()
data := &MetricData{
Name: c.name,
Type: MetricTypeCounter,
Help: c.help,
Labels: c.labels,
Values: make(map[string]float64),
Timestamp: time.Now(),
}
// 添加主指标值
if c.value > 0 {
data.Values[""] = c.value
data.Samples = append(data.Samples, Sample{
Labels: make(map[string]string),
Value: c.value,
Timestamp: data.Timestamp,
})
}
// 添加带标签的指标值
for key, child := range c.labelValues {
if child.value > 0 {
data.Values[key] = child.value
labels := c.parseLabelKey(key)
data.Samples = append(data.Samples, Sample{
Labels: labels,
Value: child.value,
Timestamp: data.Timestamp,
})
}
}
return data
}
// 生成标签键
func (c *Counter) generateLabelKey(values []string) string {
return fmt.Sprintf("%v", values)
}
// 解析标签键
func (c *Counter) parseLabelKey(key string) map[string]string {
labels := make(map[string]string)
// 简化的解析逻辑，实际应该更复杂
if key != "" {
values := []string{}
fmt.Sscanf(key, "%v", &values)
for i, value := range values {
if i < len(c.labels) {
labels[c.labels[i]] = value
}
}
}
return labels
}
// 仪表盘指标
type Gauge struct {
name string
help string
labels []string
value float64
mutex sync.RWMutex
labelValues map[string]*Gauge
}
// 创建仪表盘
func NewGauge(name, help string, labels ...string) *Gauge {
return &Gauge{
name: name,
help: help,
labels: labels,
labelValues: make(map[string]*Gauge),
}
}
// 获取指标名称
func (g *Gauge) Name() string {
return g.name
}
// 获取指标类型
func (g *Gauge) Type() MetricType {
return MetricTypeGauge
}
// 获取指标描述
func (g *Gauge) Help() string {
return g.help
}
// 获取指标标签
func (g *Gauge) Labels() []string {
return g.labels
}
// 设置值
func (g *Gauge) Set(value float64) {
g.mutex.Lock()
defer g.mutex.Unlock()
g.value = value
}
// 增加值
func (g *Gauge) Add(value float64) {
g.mutex.Lock()
defer g.mutex.Unlock()
g.value += value
}
// 减少值
func (g *Gauge) Sub(value float64) {
g.mutex.Lock()
defer g.mutex.Unlock()
g.value -= value
}
// 设置为当前时间
func (g *Gauge) SetToCurrentTime() {
g.Set(float64(time.Now().Unix()))
}
// 带标签设置
func (g *Gauge) WithLabelValues(values ...string) *Gauge {
if len(values) != len(g.labels) {
return g
}
key := g.generateLabelKey(values)
g.mutex.RLock()
child, exists := g.labelValues[key]
g.mutex.RUnlock()
if !exists {
g.mutex.Lock()
if child, exists = g.labelValues[key]; !exists {
child = &Gauge{
name: g.name,
help: g.help,
labels: g.labels,
}
g.labelValues[key] = child
}
g.mutex.Unlock()
}
return child
}
// 获取指标值
func (g *Gauge) Value() float64 {
g.mutex.RLock()
defer g.mutex.RUnlock()
return g.value
}
// 收集指标数据
func (g *Gauge) Collect() *MetricData {
g.mutex.RLock()
defer g.mutex.RUnlock()
data := &MetricData{
Name: g.name,
Type: MetricTypeGauge,
Help: g.help,
Labels: g.labels,
Values: make(map[string]float64),
Timestamp: time.Now(),
}
// 添加主指标值
data.Values[""] = g.value
data.Samples = append(data.Samples, Sample{
Labels: make(map[string]string),
Value: g.value,
Timestamp: data.Timestamp,
})
// 添加带标签的指标值
for key, child := range g.labelValues {
data.Values[key] = child.value
labels := g.parseLabelKey(key)
data.Samples = append(data.Samples, Sample{
Labels: labels,
Value: child.value,
Timestamp: data.Timestamp,
})
}
return data
}
// 直方图指标
type Histogram struct {
name string
help string
labels []string
buckets []float64
counts []uint64
sum float64
count uint64
mutex sync.RWMutex
labelValues map[string]*Histogram
}
// 创建直方图
func NewHistogram(name, help string, buckets []float64, labels ...string) *Histogram {
if len(buckets) == 0 {
// 使用默认桶边界
buckets = []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10}
}
// 确保桶是排序的
sort.Float64s(buckets)
return &Histogram{
name: name,
help: help,
labels: labels,
buckets: buckets,
counts: make([]uint64, len(buckets)+1),
labelValues: make(map[string]*Histogram),
}
}
// 观察值
func (h *Histogram) Observe(value float64) {
h.mutex.Lock()
defer h.mutex.Unlock()
h.sum += value
h.count++
// 找到合适的桶
for i, bucket := range h.buckets {
if value <= bucket {
h.counts[i]++
return
}
}
// 超过所有桶
h.counts[len(h.buckets)]++
}
// 带标签观察
func (h *Histogram) WithLabelValues(values ...string) *Histogram {
if len(values) != len(h.labels) {
return h
}
key := h.generateLabelKey(values)
h.mutex.RLock()
child, exists := h.labelValues[key]
h.mutex.RUnlock()
if !exists {
h.mutex.Lock()
if child, exists = h.labelValues[key]; !exists {
child = NewHistogram(h.name, h.help, h.buckets, h.labels...)
h.labelValues[key] = child
}
h.mutex.Unlock()
}
return child
}
// 获取指标值
func (h *Histogram) Value() float64 {
h.mutex.RLock()
defer h.mutex.RUnlock()
return h.sum
}
// 获取总数
func (h *Histogram) Count() uint64 {
h.mutex.RLock()
defer h.mutex.RUnlock()
return h.count
}
// 收集指标数据
func (h *Histogram) Collect() *MetricData {
h.mutex.RLock()
defer h.mutex.RUnlock()
data := &MetricData{
Name: h.name,
Type: MetricTypeHistogram,
Help: h.help,
Labels: h.labels,
Values: make(map[string]float64),
Timestamp: time.Now(),
}
// 添加桶计数
for i, bucket := range h.buckets {
bucketName := fmt.Sprintf("bucket{le=\"%f\"}", bucket)
data.Values[bucketName] = float64(h.counts[i])
}
// 添加+Inf桶
data.Values["bucket{le=\"+Inf\"}"] = float64(h.counts[len(h.buckets)])
// 添加总数和总和
data.Values["count"] = float64(h.count)
data.Values["sum"] = h.sum
return data
}
// 默认指标注册表
type DefaultRegistry struct {
collectors map[string]Collector
mutex sync.RWMutex
}
// 创建默认注册表
func NewDefaultRegistry() *DefaultRegistry {
return &DefaultRegistry{
collectors: make(map[string]Collector),
}
}
// 注册收集器
func (r *DefaultRegistry) Register(name string, collector Collector) error {
r.mutex.Lock()
defer r.mutex.Unlock()
if _, exists := r.collectors[name]; exists {
return fmt.Errorf("收集器已存在: %s", name)
}
r.collectors[name] = collector
return nil
}
// 注销收集器
func (r *DefaultRegistry) Unregister(name string) error {
r.mutex.Lock()
defer r.mutex.Unlock()
if _, exists := r.collectors[name]; !exists {
return fmt.Errorf("收集器不存在: %s", name)
}
delete(r.collectors, name)
return nil
}
// 收集所有数据
func (r *DefaultRegistry) Gather() ([]*MetricData, error) {
r.mutex.RLock()
defer r.mutex.RUnlock()
var allData []*MetricData
for _, collector := range r.collectors {
data, err := collector.Collect()
if err != nil {
return nil, fmt.Errorf("收集指标失败: %s", err.Error())
}
allData = append(allData, data...)
}
return allData, nil
}
// 获取收集器
func (r *DefaultRegistry) GetCollector(name string) (Collector, bool) {
r.mutex.RLock()
defer r.mutex.RUnlock()
collector, exists := r.collectors[name]
return collector, exists
}
// 指标收集器实现
type DefaultCollector struct {
metrics map[string]Metric
mutex sync.RWMutex
}
// 创建默认收集器
func NewDefaultCollector() *DefaultCollector {
return &DefaultCollector{
metrics: make(map[string]Metric),
}
}
// 注册指标
func (c *DefaultCollector) Register(metric Metric) error {
c.mutex.Lock()
defer c.mutex.Unlock()
if _, exists := c.metrics[metric.Name()]; exists {
return fmt.Errorf("指标已存在: %s", metric.Name())
}
c.metrics[metric.Name()] = metric
return nil
}
// 注销指标
func (c *DefaultCollector) Unregister(name string) error {
c.mutex.Lock()
defer c.mutex.Unlock()
if _, exists := c.metrics[name]; !exists {
return fmt.Errorf("指标不存在: %s", name)
}
delete(c.metrics, name)
return nil
}
// 获取指标
func (c *DefaultCollector) GetMetric(name string) (Metric, bool) {
c.mutex.RLock()
defer c.mutex.RUnlock()
metric, exists := c.metrics[name]
return metric, exists
}
// 收集所有指标
func (c *DefaultCollector) Collect() ([]*MetricData, error) {
c.mutex.RLock()
defer c.mutex.RUnlock()
var data []*MetricData
for _, metric := range c.metrics {
data = append(data, metric.Collect())
}
return data, nil
}
---
02.指标收集器实现
a.系统指标收集器
a.CPU使用率
收集CPU使用率、负载平均值等指标。
b.内存使用情况
收集内存使用量、使用率、GC信息等。
c.磁盘IO统计
收集磁盘读写速度、IO等待时间等。
d.网络统计
收集网络流量、连接数、错误率等。
b.应用指标收集器
a.HTTP请求指标
收集请求数量、响应时间、状态码分布等。
b.gRPC调用指标
收集gRPC调用的数量、延迟、错误率等。
c.数据库连接池指标
收集连接池使用情况、查询性能等。
d.缓存指标
收集缓存命中率、读写性能等。
c.业务指标收集器
a.业务指标定义
支持自定义业务指标的收集和统计。
b.事件计数
收集业务事件的计数和分布。
c.性能指标
收集业务流程的性能指标。
d.指标收集器示例
---
// 指标收集器实现示例
package collectors
import (
"context"
"fmt"
"runtime"
"sync"
"time"
)
// 系统指标收集器
type SystemCollector struct {
cpuUsage prometheus.Gauge
memUsage prometheus.Gauge
goroutineCount prometheus.Gauge
gcDuration prometheus.Histogram
mutex sync.RWMutex
}
// 创建系统指标收集器
func NewSystemCollector() *SystemCollector {
collector := &SystemCollector{
cpuUsage: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "system_cpu_usage_percent",
Help: "CPU使用率百分比",
}),
memUsage: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "system_memory_usage_percent",
Help: "内存使用率百分比",
}),
goroutineCount: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "system_goroutine_count",
Help: "当前goroutine数量",
}),
gcDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
Name: "system_gc_duration_seconds",
Help: "GC耗时",
Buckets: []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
}),
}
return collector
}
// 开始收集系统指标
func (c *SystemCollector) Start(ctx context.Context) error {
ticker := time.NewTicker(5 * time.Second)
defer ticker.Stop()
// 启动GC监控
go c.monitorGC(ctx)
for {
select {
case <-ticker.C:
c.collectMetrics()
case <-ctx.Done():
return nil
}
}
}
// 收集系统指标
func (c *SystemCollector) collectMetrics() {
c.mutex.Lock()
defer c.mutex.Unlock()
// 收集goroutine数量
c.goroutineCount.Set(float64(runtime.NumGoroutine()))
// 收集内存使用情况
var m runtime.MemStats
runtime.ReadMemStats(&m)
memoryUsage := float64(m.Alloc) / float64(m.Sys) * 100
c.memUsage.Set(memoryUsage)
// 收集CPU使用率（简化实现）
// 实际实现中应该使用更精确的方法
cpuUsage := c.calculateCPUUsage()
c.cpuUsage.Set(cpuUsage)
}
// 计算CPU使用率
func (c *SystemCollector) calculateCPUUsage() float64 {
// 简化的CPU使用率计算
// 实际实现应该使用系统调用获取更精确的数据
return float64(runtime.NumCPU()) * 0.1 // 模拟值
}
// 监控GC
func (c *SystemCollector) monitorGC(ctx context.Context) {
var lastGCStats time.Time
ticker := time.NewTicker(100 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ticker.C:
var m runtime.MemStats
runtime.ReadMemStats(&m)
if m.LastGC > 0 {
lastGCTime := time.Unix(0, int64(m.LastGC))
if lastGCStats.IsZero() {
lastGCStats = lastGCTime
} else {
duration := lastGCTime.Sub(lastGCStats).Seconds()
if duration > 0 {
c.gcDuration.Observe(duration)
}
lastGCStats = lastGCTime
}
}
case <-ctx.Done():
return
}
}
}
// HTTP指标收集器
type HTTPCollector struct {
requestsTotal *prometheus.CounterVec
requestDuration *prometheus.HistogramVec
responseSize *prometheus.HistogramVec
activeRequests prometheus.Gauge
mutex sync.RWMutex
}
// 创建HTTP指标收集器
func NewHTTPCollector() *HTTPCollector {
return &HTTPCollector{
requestsTotal: prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "HTTP请求总数",
},
[]string{"method", "path", "status"},
),
requestDuration: prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP请求耗时",
Buckets: []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
},
[]string{"method", "path", "status"},
),
responseSize: prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_response_size_bytes",
Help: "HTTP响应大小",
Buckets: []float64{100, 500, 1000, 5000, 10000, 50000, 100000, 500000, 1000000, 5000000, 10000000},
},
[]string{"method", "path", "status"},
),
activeRequests: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "http_active_requests",
Help: "当前活跃的HTTP请求数",
}),
}
}
// 记录请求开始
func (c *HTTPCollector) RequestStarted(method, path string) {
c.activeRequests.Inc()
}
// 记录请求完成
func (c *HTTPCollector) RequestCompleted(method, path string, statusCode int, duration time.Duration, responseSize int64) {
c.activeRequests.Dec()
labels := prometheus.Labels{
"method": method,
"path": path,
"status": fmt.Sprintf("%d", statusCode),
}
c.requestsTotal.With(labels).Inc()
c.requestDuration.With(labels).Observe(duration.Seconds())
c.responseSize.With(labels).Observe(float64(responseSize))
}
// 数据库指标收集器
type DBCollector struct {
connectionsActive prometheus.Gauge
connectionsIdle prometheus.Gauge
connectionsMax prometheus.Gauge
queryDuration *prometheus.HistogramVec
queryTotal *prometheus.CounterVec
queryErrors *prometheus.CounterVec
transactionsActive prometheus.Gauge
transactionDuration *prometheus.HistogramVec
mutex sync.RWMutex
}
// 创建数据库指标收集器
func NewDBCollector() *DBCollector {
return &DBCollector{
connectionsActive: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "db_connections_active",
Help: "活跃数据库连接数",
}),
connectionsIdle: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "db_connections_idle",
Help: "空闲数据库连接数",
}),
connectionsMax: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "db_connections_max",
Help: "最大数据库连接数",
}),
queryDuration: prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "db_query_duration_seconds",
Help: "数据库查询耗时",
Buckets: []float64{0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10},
},
[]string{"operation", "table"},
),
queryTotal: prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "db_queries_total",
Help: "数据库查询总数",
},
[]string{"operation", "table", "status"},
),
queryErrors: prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "db_query_errors_total",
Help: "数据库查询错误总数",
},
[]string{"operation", "table", "error"},
),
transactionsActive: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "db_transactions_active",
Help: "活跃事务数",
}),
transactionDuration: prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "db_transaction_duration_seconds",
Help: "数据库事务耗时",
Buckets: []float64{0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60},
},
[]string{"operation"},
),
}
}
// 更新连接池指标
func (c *DBCollector) UpdateConnectionStats(active, idle, max int) {
c.connectionsActive.Set(float64(active))
c.connectionsIdle.Set(float64(idle))
c.connectionsMax.Set(float64(max))
}
// 记录查询开始
func (c *DBCollector) QueryStarted(operation, table string) {
// 可以在这里记录查询开始时间
}
// 记录查询完成
func (c *DBCollector) QueryCompleted(operation, table string, duration time.Duration, err error) {
labels := prometheus.Labels{
"operation": operation,
"table": table,
}
statusLabels := prometheus.Labels{
"operation": operation,
"table": table,
"status": "success",
}
if err != nil {
statusLabels["status"] = "error"
errorLabels := prometheus.Labels{
"operation": operation,
"table": table,
"error": err.Error(),
}
c.queryErrors.With(errorLabels).Inc()
}
c.queryTotal.With(statusLabels).Inc()
c.queryDuration.With(labels).Observe(duration.Seconds())
}
// 记录事务开始
func (c *DBCollector) TransactionStarted(operation string) {
c.transactionsActive.Inc()
}
// 记录事务完成
func (c *DBCollector) TransactionCompleted(operation string, duration time.Duration, err error) {
c.transactionsActive.Dec()
labels := prometheus.Labels{
"operation": operation,
}
c.transactionDuration.With(labels).Observe(duration.Seconds())
}
// 缓存指标收集器
type CacheCollector struct {
hits prometheus.Counter
misses prometheus.Counter
sets prometheus.Counter
deletes prometheus.Counter
evictions prometheus.Counter
hitRatio prometheus.Gauge
itemCount prometheus.Gauge
memoryUsage prometheus.Gauge
getDuration prometheus.Histogram
setDuration prometheus.Histogram
mutex sync.RWMutex
}
// 创建缓存指标收集器
func NewCacheCollector() *CacheCollector {
return &CacheCollector{
hits: prometheus.NewCounter(prometheus.CounterOpts{
Name: "cache_hits_total",
Help: "缓存命中总数",
}),
misses: prometheus.NewCounter(prometheus.CounterOpts{
Name: "cache_misses_total",
Help: "缓存未命中总数",
}),
sets: prometheus.NewCounter(prometheus.CounterOpts{
Name: "cache_sets_total",
Help: "缓存设置总数",
}),
deletes: prometheus.NewCounter(prometheus.CounterOpts{
Name: "cache_deletes_total",
Help: "缓存删除总数",
}),
evictions: prometheus.NewCounter(prometheus.CounterOpts{
Name: "cache_evictions_total",
Help: "缓存驱逐总数",
}),
hitRatio: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "cache_hit_ratio",
Help: "缓存命中率",
}),
itemCount: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "cache_item_count",
Help: "缓存项数量",
}),
memoryUsage: prometheus.NewGauge(prometheus.GaugeOpts{
Name: "cache_memory_usage_bytes",
Help: "缓存内存使用量",
}),
getDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
Name: "cache_get_duration_seconds",
Help: "缓存获取操作耗时",
Buckets: []float64{0.000001, 0.000005, 0.00001, 0.000025, 0.00005, 0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01},
}),
setDuration: prometheus.NewHistogram(prometheus.HistogramOpts{
Name: "cache_set_duration_seconds",
Help: "缓存设置操作耗时",
Buckets: []float64{0.000001, 0.000005, 0.00001, 0.000025, 0.00005, 0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01},
}),
}
}
// 记录缓存命中
func (c *CacheCollector) RecordHit() {
c.hits.Inc()
c.updateHitRatio()
}
// 记录缓存未命中
func (c *CacheCollector) RecordMiss() {
c.misses.Inc()
c.updateHitRatio()
}
// 记录缓存设置
func (c *CacheCollector) RecordSet(duration time.Duration) {
c.sets.Inc()
c.setDuration.Observe(duration.Seconds())
}
// 记录缓存删除
func (c *CacheCollector) RecordDelete() {
c.deletes.Inc()
}
// 记录缓存驱逐
func (c *CacheCollector) RecordEviction() {
c.evictions.Inc()
}
// 记录缓存获取操作
func (c *CacheCollector) RecordGet(duration time.Duration) {
c.getDuration.Observe(duration.Seconds())
}
// 更新缓存统计
func (c *CacheCollector) UpdateStats(itemCount int, memoryUsage int64) {
c.itemCount.Set(float64(itemCount))
c.memoryUsage.Set(float64(memoryUsage))
}
// 更新命中率
func (c *CacheCollector) updateHitRatio() {
hits := c.hits.Get()
total := hits + c.misses.Get()
if total > 0 {
ratio := hits / total
c.hitRatio.Set(ratio)
}
}
---
2.7 链路追踪组件 Tracing
01.链路追踪架构设计
a.分布式追踪架构
a.追踪数据收集
在应用程序中收集追踪数据，包括span、事件、标签等。
b.追踪数据传输
将追踪数据传输到追踪后端，支持多种传输协议。
c.追踪数据处理
对追踪数据进行处理、聚合和分析。
d.追踪数据存储
将处理后的追踪数据存储到时序数据库。
b.OpenTelemetry集成
a.Tracer Provider
提供统一的追踪器创建和管理。
b.Span管理
管理span的创建、结束和属性设置。
c.Context传播
实现跨服务的追踪上下文传播。
d.资源属性
定义服务和实例的属性信息。
c.链路追踪系统示例
---
// Tracing链路追踪系统架构示例
package tracing
import (
"context"
"fmt"
"sync"
"time"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/codes"
"go.opentelemetry.io/otel/propagation"
"go.opentelemetry.io/otel/trace"
)
// 追踪器提供者
type TracerProvider interface {
// 创建追踪器
Tracer(name string, opts ...trace.TracerOption) trace.Tracer
// 强制刷新缓冲区
ForceFlush(ctx context.Context) error
// 关闭追踪器提供者
Shutdown(ctx context.Context) error
}
// Span构建器
type SpanBuilder struct {
name string
tracer trace.Tracer
kind trace.SpanKind
timestamp time.Time
links []trace.Link
attributes []attribute.KeyValue
options []trace.SpanStartOption
}
// 追踪上下文
type TraceContext struct {
TraceID trace.TraceID
SpanID trace.SpanID
TraceFlags trace.TraceFlags
TraceState trace.TraceState
Remote bool
}
// 自定义追踪器提供者
type CustomTracerProvider struct {
tracers map[string]trace.Tracer
mutex sync.RWMutex
config *TracerProviderConfig
exporter SpanExporter
}
// 追踪器提供者配置
type TracerProviderConfig struct {
ServiceName string `json:"service_name"`
ServiceVersion string `json:"service_version"`
Environment string `json:"environment"`
SampleRate float64 `json:"sample_rate"`
BatchSize int `json:"batch_size"`
BatchTimeout time.Duration `json:"batch_timeout"`
MaxExportBatchSize int `json:"max_export_batch_size"`
ResourceAttributes map[string]string `json:"resource_attributes"`
}
// Span导出器
type SpanExporter interface {
// 导出span批次
ExportSpans(ctx context.Context, spans []ReadOnlySpan) error
// 关闭导出器
Shutdown(ctx context.Context) error
}
// 只读Span接口
type ReadOnlySpan interface {
// 获取Span上下文
SpanContext() trace.SpanContext
// 获取父Span上下文
Parent() trace.SpanContext
// 获取Span名称
Name() string
// 获取Span类型
Kind() trace.SpanKind
// 获取开始时间
StartTime() time.Time
// 获取结束时间
EndTime() time.Time
// 获取属性
Attributes() []attribute.KeyValue
// 获取链接
Links() []trace.Link
// 获取状态
Status() codes.Code
// 获取状态描述
StatusMessage() string
// 是否记录事件
HasEvents() bool
// 获取事件
Events() []trace.Event
// 获取资源
Resource() *Resource
// 获取instrumentation库信息
InstrumentationLibrary() InstrumentationLibrary
}
// 资源信息
type Resource struct {
Attributes []attribute.KeyValue
SchemaURL string
}
// Instrumentation库信息
type InstrumentationLibrary struct {
Name string
Version string
}
// 创建自定义追踪器提供者
func NewCustomTracerProvider(config *TracerProviderConfig, exporter SpanExporter) *CustomTracerProvider {
return &CustomTracerProvider{
tracers: make(map[string]trace.Tracer),
config: config,
exporter: exporter,
}
}
// 创建追踪器
func (p *CustomTracerProvider) Tracer(name string, opts ...trace.TracerOption) trace.Tracer {
p.mutex.Lock()
defer p.mutex.Unlock()
if tracer, exists := p.tracers[name]; exists {
return tracer
}
tracer := &CustomTracer{
name: name,
provider: p,
config: p.config,
}
p.tracers[name] = tracer
return tracer
}
// 强制刷新
func (p *CustomTracerProvider) ForceFlush(ctx context.Context) error {
if p.exporter != nil {
// 这里应该实现批量导出逻辑
return p.exporter.ExportSpans(ctx, nil)
}
return nil
}
// 关闭提供者
func (p *CustomTracerProvider) Shutdown(ctx context.Context) error {
if p.exporter != nil {
return p.exporter.Shutdown(ctx)
}
return nil
}
// 自定义追踪器
type CustomTracer struct {
name string
provider *CustomTracerProvider
config *TracerProviderConfig
}
// 开始Span
func (t *CustomTracer) Start(ctx context.Context, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span) {
// 创建Span构建器
builder := &SpanBuilder{
name: spanName,
tracer: t,
kind: trace.SpanKindInternal,
}
// 应用选项
for _, opt := range opts {
opt(builder)
}
// 检查是否采样
if !t.shouldSample(ctx, spanName) {
// 返回无操作span
noopSpan := trace.NoOpSpan{}
return trace.ContextWithNoSpan(ctx), noopSpan
}
// 获取或创建Span上下文
spanContext := t.createSpanContext(ctx)
// 创建自定义Span
span := &CustomSpan{
spanContext: spanContext,
name: spanName,
kind: builder.kind,
startTime: builder.timestamp,
attributes: make([]attribute.KeyValue, 0),
events: make([]trace.Event, 0),
links: builder.links,
tracer: t,
mutex: sync.RWMutex{},
}
// 添加资源属性
t.addResourceAttributes(span)
// 将Span添加到上下文
return trace.ContextWithSpan(ctx, span), span
}
// 检查是否应该采样
func (t *CustomTracer) shouldSample(ctx context.Context, spanName string) bool {
// 简化的采样逻辑，实际应该使用更复杂的采样策略
return t.config.SampleRate > 0
}
// 创建Span上下文
func (t *CustomTracer) createSpanContext(ctx context.Context) trace.SpanContext {
parentSpan := trace.SpanFromContext(ctx)
if parentSpan != nil && parentSpan.SpanContext().IsValid() {
// 创建子Span上下文
parentCtx := parentSpan.SpanContext()
traceID := parentCtx.TraceID
spanID := t.generateSpanID()
return trace.NewSpanContext(trace.SpanContextConfig{
TraceID: traceID,
SpanID: spanID,
TraceFlags: parentCtx.TraceFlags,
TraceState: parentCtx.TraceState,
Remote: false,
})
} else {
// 创建根Span上下文
traceID := t.generateTraceID()
spanID := t.generateSpanID()
return trace.NewSpanContext(trace.SpanContextConfig{
TraceID: traceID,
SpanID: spanID,
TraceFlags: trace.FlagsSampled,
Remote: false,
})
}
}
// 生成追踪ID
func (t *CustomTracer) generateTraceID() trace.TraceID {
// 简化的实现，实际应该使用安全的随机数生成器
var id [16]byte
// 这里应该使用crypto/rand生成随机ID
copy(id[:], "1234567890123456")
return trace.TraceID(id)
}
// 生成Span ID
func (t *CustomTracer) generateSpanID() trace.SpanID {
// 简化的实现，实际应该使用安全的随机数生成器
var id [8]byte
copy(id[:], "12345678")
return trace.SpanID(id)
}
// 添加资源属性
func (t *CustomTracer) addResourceAttributes(span *CustomSpan) {
// 添加服务信息
span.SetAttributes(
attribute.String("service.name", t.config.ServiceName),
attribute.String("service.version", t.config.ServiceVersion),
attribute.String("environment", t.config.Environment),
)
// 添加自定义资源属性
for key, value := range t.config.ResourceAttributes {
span.SetAttributes(attribute.String(key, value))
}
}
// 自定义Span
type CustomSpan struct {
spanContext trace.SpanContext
name string
kind trace.SpanKind
startTime time.Time
endTime time.Time
status codes.Code
statusMsg string
attributes []attribute.KeyValue
events []trace.Event
links []trace.Link
tracer *CustomTracer
mutex sync.RWMutex
ended bool
}
// 获取Span上下文
func (s *CustomSpan) SpanContext() trace.SpanContext {
return s.spanContext
}
// 结束Span
func (s *CustomSpan) End(options ...trace.SpanEndOption) {
s.mutex.Lock()
defer s.mutex.Unlock()
if s.ended {
return
}
s.endTime = time.Now()
s.ended = true
// 应用结束选项
for _, opt := range options {
opt(s)
}
// 导出Span
s.exportSpan()
}
// 导出Span
func (s *CustomSpan) exportSpan() {
if s.tracer.provider.exporter != nil {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
spans := []ReadOnlySpan{s}
if err := s.tracer.provider.exporter.ExportSpans(ctx, spans); err != nil {
// 记录导出失败
fmt.Printf("导出Span失败: %s\n", err.Error())
}
}
}
// 设置属性
func (s *CustomSpan) SetAttribute(kv attribute.KeyValue) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.attributes = append(s.attributes, kv)
}
// 设置多个属性
func (s *CustomSpan) SetAttributes(attrs ...attribute.KeyValue) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.attributes = append(s.attributes, attrs...)
}
// 添加事件
func (s *CustomSpan) AddEvent(name string, options ...trace.EventOption) {
s.mutex.Lock()
defer s.mutex.Unlock()
event := trace.Event{
Name: name,
}
// 应用事件选项
for _, opt := range options {
opt(&event)
}
s.events = append(s.events, event)
}
// 记录错误
func (s *CustomSpan) RecordError(err error, options ...trace.EventOption) {
s.mutex.Lock()
defer s.mutex.Unlock()
// 设置Span状态
s.status = codes.Error
s.statusMsg = err.Error()
// 添加错误事件
eventOptions := []trace.EventOption{
trace.WithAttributes(
attribute.String("exception.type", fmt.Sprintf("%T", err)),
attribute.String("exception.message", err.Error()),
),
}
eventOptions = append(eventOptions, options...)
s.AddEvent("exception", eventOptions...)
}
// 设置状态
func (s *CustomSpan) SetStatus(code codes.Code, description string) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.status = code
s.statusMsg = description
}
// 设置名称
func (s *CustomSpan) SetName(name string) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.name = name
}
// 是否被记录
func (s *CustomSpan) IsRecording() bool {
return !s.ended
}
// 获取追踪器
func (s *CustomSpan) TracerProvider() trace.TracerProvider {
return s.tracer.provider
}
// 获取开始时间
func (s *CustomSpan) StartTime() time.Time {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.startTime
}
// 获取结束时间
func (s *CustomSpan) EndTime() time.Time {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.endTime
}
// 获取属性（只读）
func (s *CustomSpan) Attributes() []attribute.KeyValue {
s.mutex.RLock()
defer s.mutex.RUnlock()
attrs := make([]attribute.KeyValue, len(s.attributes))
copy(attrs, s.attributes)
return attrs
}
// 获取事件（只读）
func (s *CustomSpan) Events() []trace.Event {
s.mutex.RLock()
defer s.mutex.RUnlock()
events := make([]trace.Event, len(s.events))
copy(events, s.events)
return events
}
// 获取状态
func (s *CustomSpan) Status() codes.Code {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.status
}
// 获取状态描述
func (s *CustomSpan) StatusMessage() string {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.statusMsg
}
// 获取Span名称
func (s *CustomSpan) Name() string {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.name
}
// 获取Span类型
func (s *CustomSpan) Kind() trace.SpanKind {
s.mutex.RLock()
defer s.mutex.RUnlock()
return s.kind
}
---
02.上下文传播机制
a.跨进程传播
a.HTTP Header传播
通过HTTP头传递追踪上下文信息。
b.gRPC Metadata传播
通过gRPC元数据传递追踪上下文。
c.消息队列传播
通过消息队列的消息属性传递上下文。
b.传播格式
a.W3C Trace Context
支持W3C标准的trace-context格式。
b.B3格式
支持Zipkin的B3传播格式。
c.Jaeger格式
支持Jaeger的传播格式。
c.传播策略
a.注入策略
定义如何将追踪上下文注入到传输层。
b.提取策略
定义如何从传输层提取追踪上下文。
c.复合传播
支持多种传播格式的组合使用。
d.上下文传播示例
---
// 上下文传播机制实现示例
package propagation
import (
"context"
"fmt"
"net/http"
"strings"
"go.opentelemetry.io/otel/propagation"
"go.opentelemetry.io/otel/trace"
)
// 自定义传播器
type CustomPropagator struct {
injectors []propagation.Injector
extractors []propagation.Extractor
}
// 创建自定义传播器
func NewCustomPropagator() *CustomPropagator {
return &CustomPropagator{
injectors: []propagation.Injector{
&TraceContextInjector{},
&BaggageInjector{},
},
extractors: []propagation.Extractor{
&TraceContextExtractor{},
&BaggageExtractor{},
},
}
}
// 注入传播
func (p *CustomPropagator) Inject(ctx context.Context, carrier propagation.TextMapCarrier) {
for _, injector := range p.injectors {
injector.Inject(ctx, carrier)
}
}
// 提取传播
func (p *CustomPropagator) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context {
for _, extractor := range p.extractors {
ctx = extractor.Extract(ctx, carrier)
}
return ctx
}
// 获取传播字段
func (p *CustomPropagator) Fields() []string {
fields := make(map[string]bool)
for _, injector := range p.injectors {
for _, field := range injector.Fields() {
fields[field] = true
}
}
result := make([]string, 0, len(fields))
for field := range fields {
result = append(result, field)
}
return result
}
// Trace Context注入器
type TraceContextInjector struct{}
// 注入Trace Context
func (i *TraceContextInjector) Inject(ctx context.Context, carrier propagation.TextMapCarrier) {
span := trace.SpanFromContext(ctx)
if span == nil {
return
}
spanContext := span.SpanContext()
if !spanContext.IsValid() {
return
}
// 注入traceparent
carrier.Set("traceparent", fmt.Sprintf("00-%s-%s-%02x",
spanContext.TraceID(),
spanContext.SpanID(),
spanContext.TraceFlags()))
// 注入tracestate
if spanContext.TraceState().Len() > 0 {
carrier.Set("tracestate", spanContext.TraceState().String())
}
}
// 获取字段列表
func (i *TraceContextInjector) Fields() []string {
return []string{"traceparent", "tracestate"}
}
// Trace Context提取器
type TraceContextExtractor struct{}
// 提取Trace Context
func (e *TraceContextExtractor) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context {
// 提取traceparent
traceParent := carrier.Get("traceparent")
if traceParent == "" {
return ctx
}
// 解析traceparent格式: 00-traceId-spanId-flags
parts := strings.Split(traceParent, "-")
if len(parts) != 4 || parts[0] != "00" {
return ctx
}
// 解析Trace ID
traceID, err := trace.TraceIDFromHex(parts[1])
if err != nil {
return ctx
}
// 解析Span ID
spanID, err := trace.SpanIDFromHex(parts[2])
if err != nil {
return ctx
}
// 解析Flags
var flags trace.TraceFlags
if len(parts[3]) >= 2 {
if _, err := fmt.Sscanf(parts[3], "%02x", &flags); err != nil {
return ctx
}
}
// 创建Span上下文
spanContext := trace.NewSpanContext(trace.SpanContextConfig{
TraceID: traceID,
SpanID: spanID,
TraceFlags: flags,
Remote: true,
})
// 提取tracestate
var traceState trace.TraceState
traceStateStr := carrier.Get("tracestate")
if traceStateStr != "" {
traceState, _ = trace.ParseTraceState(traceStateStr)
}
return trace.ContextWithRemoteSpanContext(ctx, spanContext)
}
// 获取字段列表
func (e *TraceContextExtractor) Fields() []string {
return []string{"traceparent", "tracestate"}
}
// Baggage注入器
type BaggageInjector struct{}
// 注入Baggage
func (i *BaggageInjector) Inject(ctx context.Context, carrier propagation.TextMapCarrier) {
// 获取所有baggage项
baggage := baggage.FromContext(ctx)
if baggage.Len() == 0 {
return
}
// 遍历baggage项并注入
baggage.ForEach(func(k, v attribute.KeyValue) bool {
carrier.Set("baggage", fmt.Sprintf("%s=%s", k, v.AsString()))
return true
})
}
// 获取字段列表
func (i *BaggageInjector) Fields() []string {
return []string{"baggage"}
}
// Baggage提取器
type BaggageExtractor struct{}
// 提取Baggage
func (e *BaggageExtractor) Extract(ctx context.Context, carrier propagation.TextMapCarrier) context.Context {
baggageStr := carrier.Get("baggage")
if baggageStr == "" {
return ctx
}
// 解析baggage字符串
member, err := baggage.ParseMember(baggageStr)
if err != nil {
return ctx
}
// 创建baggage并添加到上下文
b := baggage.New()
b = b.Set(string(member.Key), member.Value)
return baggage.ContextWithBaggage(ctx, b)
}
// 获取字段列表
func (e *BaggageExtractor) Fields() []string {
return []string{"baggage"}
}
// HTTP头部传播载体
type HTTPHeadersCarrier struct {
headers http.Header
}
// 创建HTTP头部载体
func NewHTTPHeadersCarrier(headers http.Header) *HTTPHeadersCarrier {
return &HTTPHeadersCarrier{headers: headers}
}
// 获取值
func (c *HTTPHeadersCarrier) Get(key string) string {
return c.headers.Get(key)
}
// 设置值
func (c *HTTPHeadersCarrier) Set(key string, value string) {
c.headers.Set(key, value)
}
// 键列表
func (c *HTTPHeadersCarrier) Keys() []string {
keys := make([]string, 0, len(c.headers))
for k := range c.headers {
keys = append(keys, k)
}
return keys
}
// gRPC元数据传播载体
type GRPCMetadataCarrier struct {
metadata metadata.MD
}
// 创建gRPC元数据载体
func NewGRPCMetadataCarrier(md metadata.MD) *GRPCMetadataCarrier {
return &GRPCMetadataCarrier{metadata: md}
}
// 获取值
func (c *GRPCMetadataCarrier) Get(key string) string {
values := c.metadata.Get(key)
if len(values) > 0 {
return values[0]
}
return ""
}
// 设置值
func (c *GRPCMetadataCarrier) Set(key string, value string) {
c.metadata.Set(key, value)
}
// 键列表
func (c *GRPCMetadataCarrier) Keys() []string {
keys := make([]string, 0, len(c.metadata))
for k := range c.metadata {
keys = append(keys, k)
}
return keys
}
// 传播管理器
type PropagationManager struct {
propagator propagation.TextMapPropagator
}
// 创建传播管理器
func NewPropagationManager() *PropagationManager {
return &PropagationManager{
propagator: propagation.NewCompositeTextMapPropagator(
propagation.TraceContext{},
propagation.Baggage{},
),
}
}
// 从HTTP请求提取上下文
func (m *PropagationManager) ExtractFromHTTP(ctx context.Context, r *http.Request) context.Context {
carrier := NewHTTPHeadersCarrier(r.Header)
return m.propagator.Extract(ctx, carrier)
}
// 注入到HTTP响应
func (m *PropagationManager) InjectToHTTP(ctx context.Context, w http.ResponseWriter) {
carrier := NewHTTPHeadersCarrier(w.Header())
m.propagator.Inject(ctx, carrier)
}
// 从gRPC上下文提取
func (m *PropagationManager) ExtractFromGRPC(ctx context.Context, md metadata.MD) context.Context {
carrier := NewGRPCMetadataCarrier(md)
return m.propagator.Extract(ctx, carrier)
}
// 注入到gRPC上下文
func (m *PropagationManager) InjectToGRPC(ctx context.Context) context.Context {
md := metadata.New(nil)
carrier := NewGRPCMetadataCarrier(md)
m.propagator.Inject(ctx, carrier)
return metadata.NewOutgoingContext(ctx, md)
}
---
03.Span导出器实现
a.Jaeger导出器
a.UDP传输
支持通过UDP协议发送追踪数据到Jaeger Agent。
b.HTTP传输
支持通过HTTP协议直接发送到Jaeger Collector。
c.批量发送
支持批量发送以提高性能。
b.Zipkin导出器
a.HTTP/JSON格式
使用HTTP协议和JSON格式发送到Zipkin。
b.Span转换
将OpenTelemetry Span转换为Zipkin格式。
c.错误处理
处理发送失败和重试逻辑。
c.Prometheus导出器
a.指标导出
将追踪数据转换为Prometheus指标。
b.延迟统计
统计请求延迟和错误率。
c.聚合计算
计算百分位数和平均值等统计信息。
d.自定义导出器
a.本地文件导出
将追踪数据保存到本地文件。
b.内存缓存导出
在内存中缓存追踪数据。
c.远程日志导出
发送到远程日志服务。
e.导出器示例
---
// Span导出器实现示例
package exporters
import (
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"sync"
"time"
"github.com/openzipkin/zipkin-go"
"go.opentelemetry.io/otel/trace"
)
// Jaeger导出器
type JaegerExporter struct {
endpoint string
serviceName string
agentEndpoint string
maxPacketSize int
batchTimeout time.Duration
client *http.Client
buffer []ReadOnlySpan
mutex sync.Mutex
stopped bool
stopChan chan struct{}
}
// Jaeger导出器配置
type JaegerExporterConfig struct {
Endpoint string `json:"endpoint"`
ServiceName string `json:"service_name"`
AgentEndpoint string `json:"agent_endpoint"`
MaxPacketSize int `json:"max_packet_size"`
BatchTimeout time.Duration `json:"batch_timeout"`
QueueSize int `json:"queue_size"`
}
// 创建Jaeger导出器
func NewJaegerExporter(config *JaegerExporterConfig) (*JaegerExporter, error) {
if config.MaxPacketSize <= 0 {
config.MaxPacketSize = 65000 // Jaeger默认UDP包大小
}
if config.BatchTimeout <= 0 {
config.BatchTimeout = 5 * time.Second
}
exporter := &JaegerExporter{
endpoint: config.Endpoint,
serviceName: config.ServiceName,
agentEndpoint: config.AgentEndpoint,
maxPacketSize: config.MaxPacketSize,
batchTimeout: config.BatchTimeout,
client: &http.Client{
Timeout: 30 * time.Second,
},
buffer: make([]ReadOnlySpan, 0, config.QueueSize),
stopChan: make(chan struct{}),
}
// 启动批量发送协程
go exporter.batchSender()
return exporter, nil
}
// 导出Spans
func (e *JaegerExporter) ExportSpans(ctx context.Context, spans []ReadOnlySpan) error {
e.mutex.Lock()
defer e.mutex.Unlock()
if e.stopped {
return fmt.Errorf("导出器已停止")
}
// 添加到缓冲区
e.buffer = append(e.buffer, spans...)
// 检查缓冲区大小
if len(e.buffer) >= cap(e.buffer) {
return e.flushBuffer(ctx)
}
return nil
}
// 批量发送器
func (e *JaegerExporter) batchSender() {
ticker := time.NewTicker(e.batchTimeout)
defer ticker.Stop()
for {
select {
case <-ticker.C:
e.mutex.Lock()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
err := e.flushBuffer(ctx)
cancel()
e.mutex.Unlock()
if err != nil {
fmt.Printf("批量发送Span失败: %s\n", err.Error())
}
case <-e.stopChan:
// 发送剩余的spans
e.mutex.Lock()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
err := e.flushBuffer(ctx)
cancel()
e.mutex.Unlock()
if err != nil {
fmt.Printf("发送剩余Span失败: %s\n", err.Error())
}
return
}
}
}
// 刷新缓冲区
func (e *JaegerExporter) flushBuffer(ctx context.Context) error {
if len(e.buffer) == 0 {
return nil
}
// 转换为Jaeger格式
jaegerSpans := e.convertToJaegerSpans(e.buffer)
// 发送到Jaeger
err := e.sendToJaeger(ctx, jaegerSpans)
if err != nil {
return fmt.Errorf("发送到Jaeger失败: %s", err.Error())
}
// 清空缓冲区
e.buffer = e.buffer[:0]
return nil
}
// 转换为Jaeger格式
func (e *JaegerExporter) convertToJaegerSpans(spans []ReadOnlySpan) []JaegerSpan {
jaegerSpans := make([]JaegerSpan, 0, len(spans))
for _, span := range spans {
jaegerSpan := JaegerSpan{
TraceID: span.SpanContext().TraceID().String(),
SpanID: span.SpanContext().SpanID().String(),
OperationName: span.Name(),
StartTime: span.StartTime().UnixNano() / 1000,
Duration: span.EndTime().Sub(span.StartTime()).Nanoseconds() / 1000,
Tags: e.convertTags(span),
Logs: e.convertLogs(span),
}
if span.Parent().IsValid() {
jaegerSpan.ParentSpanID = span.Parent().SpanID().String()
}
jaegerSpans = append(jaegerSpans, jaegerSpan)
}
return jaegerSpans
}
// 转换标签
func (e *JaegerExporter) convertTags(span ReadOnlySpan) []JaegerTag {
tags := make([]JaegerTag, 0)
// 添加服务名称
tags = append(tags, JaegerTag{
Key: "service.name",
Value: e.serviceName,
Type: "string",
})
// 添加span类型
tags = append(tags, JaegerTag{
Key: "span.kind",
Value: span.Kind().String(),
Type: "string",
})
// 添加状态
if span.Status() != codes.Ok {
tags = append(tags, JaegerTag{
Key: "error",
Value: "true",
Type: "bool",
})
if span.StatusMessage() != "" {
tags = append(tags, JaegerTag{
Key: "error.message",
Value: span.StatusMessage(),
Type: "string",
})
}
}
// 添加属性
for _, attr := range span.Attributes() {
tags = append(tags, JaegerTag{
Key: string(attr.Key),
Value: e.formatValue(attr.Value),
Type: e.getValueType(attr.Value),
})
}
return tags
}
// 转换日志
func (e *JaegerExporter) convertLogs(span ReadOnlySpan) []JaegerLog {
logs := make([]JaegerLog, 0)
for _, event := range span.Events() {
fields := make([]JaegerLogField, 0)
// 添加事件名称
fields = append(fields, JaegerLogField{
Key: "event",
Value: event.Name,
})
// 添加时间戳
fields = append(fields, JaegerLogField{
Key: "timestamp",
Value: fmt.Sprintf("%d", event.Time.UnixNano()/1000),
})
// 添加属性
for _, attr := range event.Attributes {
fields = append(fields, JaegerLogField{
Key: string(attr.Key),
Value: e.formatValue(attr.Value),
})
}
logs = append(logs, JaegerLog{
Timestamp: event.Time.UnixNano() / 1000,
Fields: fields,
})
}
return logs
}
// 格式化值
func (e *JaegerExporter) formatValue(value attribute.Value) string {
switch value.Type() {
case attribute.BOOL:
return fmt.Sprintf("%t", value.AsBool())
case attribute.INT64:
return fmt.Sprintf("%d", value.AsInt64())
case attribute.FLOAT64:
return fmt.Sprintf("%f", value.AsFloat64())
case attribute.STRING:
return value.AsString()
default:
return fmt.Sprintf("%v", value.AsInterface())
}
}
// 获取值类型
func (e *JaegerExporter) getValueType(value attribute.Value) string {
switch value.Type() {
case attribute.BOOL:
return "bool"
case attribute.INT64:
return "int64"
case attribute.FLOAT64:
return "float64"
case attribute.STRING:
return "string"
default:
return "string"
}
}
// 发送到Jaeger
func (e *JaegerExporter) sendToJaeger(ctx context.Context, spans []JaegerSpan) error {
batch := JaegerBatch{
Process: JaegerProcess{
ServiceName: e.serviceName,
Tags: []JaegerTag{
{Key: "hostname", Value: e.getHostname(), Type: "string"},
},
},
Spans: spans,
}
data, err := json.Marshal(batch)
if err != nil {
return fmt.Errorf("序列化Jaeger batch失败: %s", err.Error())
}
// 发送到Collector
if e.endpoint != "" {
return e.sendToCollector(ctx, data)
}
// 发送到Agent
if e.agentEndpoint != "" {
return e.sendToAgent(ctx, data)
}
return fmt.Errorf("未配置Jaeger端点")
}
// 发送到Collector
func (e *JaegerExporter) sendToCollector(ctx context.Context, data []byte) error {
req, err := http.NewRequestWithContext(ctx, "POST", e.endpoint+"/api/v1/spans", bytes.NewReader(data))
if err != nil {
return fmt.Errorf("创建HTTP请求失败: %s", err.Error())
}
req.Header.Set("Content-Type", "application/json")
resp, err := e.client.Do(req)
if err != nil {
return fmt.Errorf("发送HTTP请求失败: %s", err.Error())
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
body, _ := io.ReadAll(resp.Body)
return fmt.Errorf("HTTP请求失败: %d, %s", resp.StatusCode, string(body))
}
return nil
}
// 发送到Agent
func (e *JaegerExporter) sendToAgent(ctx context.Context, data []byte) error {
// 简化的UDP发送实现
// 实际实现中应该使用更可靠的UDP发送机制
conn, err := net.Dial("udp", e.agentEndpoint)
if err != nil {
return fmt.Errorf("连接Jaeger Agent失败: %s", err.Error())
}
defer conn.Close()
// 分包发送
for len(data) > 0 {
size := len(data)
if size > e.maxPacketSize {
size = e.maxPacketSize
}
_, err := conn.Write(data[:size])
if err != nil {
return fmt.Errorf("发送UDP包失败: %s", err.Error())
}
data = data[size:]
}
return nil
}
// 获取主机名
func (e *JaegerExporter) getHostname() string {
hostname, _ := os.Hostname()
if hostname == "" {
hostname = "unknown"
}
return hostname
}
// 关闭导出器
func (e *JaegerExporter) Shutdown(ctx context.Context) error {
e.mutex.Lock()
defer e.mutex.Unlock()
if e.stopped {
return nil
}
e.stopped = true
close(e.stopChan)
// 等待批量发送完成
select {
case <-time.After(10 * time.Second):
return fmt.Errorf("关闭导出器超时")
default:
return nil
}
}
// Jaeger Span结构
type JaegerSpan struct {
TraceID string `json:"traceID"`
SpanID string `json:"spanID"`
ParentSpanID string `json:"parentSpanID,omitempty"`
OperationName string `json:"operationName"`
StartTime int64 `json:"startTime"`
Duration int64 `json:"duration"`
Tags []JaegerTag `json:"tags,omitempty"`
Logs []JaegerLog `json:"logs,omitempty"`
}
// Jaeger标签结构
type JaegerTag struct {
Key string `json:"key"`
Value string `json:"value"`
Type string `json:"type,omitempty"`
}
// Jaeger日志结构
type JaegerLog struct {
Timestamp int64 `json:"timestamp"`
Fields []JaegerLogField `json:"fields"`
}
// Jaeger日志字段结构
type JaegerLogField struct {
Key string `json:"key"`
Value string `json:"value"`
}
// Jaeger批处理结构
type JaegerBatch struct {
Process JaegerProcess `json:"process"`
Spans []JaegerSpan `json:"spans"`
}
// Jaeger进程结构
type JaegerProcess struct {
ServiceName string `json:"serviceName"`
Tags []JaegerTag `json:"tags,omitempty"`
}
---
2.8 服务注册发现组件 Registry
01.服务注册发现架构
a.服务注册架构
a.服务实例管理
管理服务实例的注册、更新和注销。
b.健康检查
定期检查服务实例的健康状态。
c.元数据管理
管理服务的元数据信息。
d.事件通知
服务状态变更的事件通知机制。
b.服务发现架构
a.服务查询
提供服务的查询和发现功能。
b.负载均衡
集成多种负载均衡算法。
c.故障转移
自动处理服务实例故障。
d.缓存机制
提供服务发现的本地缓存。
c.注册中心适配器
a.Consul适配器
适配Consul服务注册中心。
b.Etcd适配器
适配Etcd分布式键值存储。
c.Nacos适配器
适配Nacos服务注册中心。
d.服务注册发现示例
---
// Registry服务注册发现架构示例
package registry
import (
"context"
"fmt"
"net"
"sync"
"time"
"github.com/go-kratos/kratos/v2/registry"
)
// 服务注册器接口
type Registrar interface {
// 注册服务
Register(ctx context.Context, service *Service) error
// 注销服务
Deregister(ctx context.Context, service *Service) error
}
// 服务发现器接口
type Discovery interface {
// 获取服务列表
GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
// 监听服务变更
Watch(ctx context.Context, serviceName string) (Watcher, error)
}
// 服务信息
type Service struct {
Name string `json:"name"`
Version string `json:"version"`
Metadata map[string]string `json:"metadata"`
Endpoints []string `json:"endpoints"`
}
// 服务实例
type ServiceInstance struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Address string `json:"address"`
Port int `json:"port"`
Metadata map[string]string `json:"metadata"`
}
// 服务监听器
type Watcher interface {
// 下一个服务变更事件
Next() ([]*ServiceInstance, error)
// 停止监听
Stop() error
}
// 服务注册发现管理器
type ServiceRegistryManager struct {
registrar Registrar
discovery Discovery
services map[string]*Service
instances map[string][]*ServiceInstance
mutex sync.RWMutex
config *RegistryConfig
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
}
// 注册中心配置
type RegistryConfig struct {
Type string `json:"type"`
Address []string `json:"address"`
Timeout time.Duration `json:"timeout"`
HeartbeatInterval time.Duration `json:"heartbeat_interval"`
HealthCheckInterval time.Duration `json:"health_check_interval"`
DeregisterCritical string `json:"deregister_critical"`
Username string `json:"username"`
Password string `json:"password"`
Token string `json:"token"`
}
// 创建服务注册发现管理器
func NewServiceRegistryManager(config *RegistryConfig) (*ServiceRegistryManager, error) {
ctx, cancel := context.WithCancel(context.Background())
manager := &ServiceRegistryManager{
services: make(map[string]*Service),
instances: make(map[string][]*ServiceInstance),
config: config,
ctx: ctx,
cancel: cancel,
}
// 初始化注册器和发现器
if err := manager.initRegistry(); err != nil {
cancel()
return nil, fmt.Errorf("初始化注册中心失败: %s", err.Error())
}
return manager, nil
}
// 初始化注册中心
func (m *ServiceRegistryManager) initRegistry() error {
switch m.config.Type {
case "consul":
consulRegistry, err := NewConsulRegistry(m.config)
if err != nil {
return err
}
m.registrar = consulRegistry
m.discovery = consulRegistry
case "etcd":
etcdRegistry, err := NewEtcdRegistry(m.config)
if err != nil {
return err
}
m.registrar = etcdRegistry
m.discovery = etcdRegistry
case "nacos":
nacosRegistry, err := NewNacosRegistry(m.config)
if err != nil {
return err
}
m.registrar = nacosRegistry
m.discovery = nacosRegistry
default:
return fmt.Errorf("不支持的注册中心类型: %s", m.config.Type)
}
return nil
}
// 注册服务
func (m *ServiceRegistryManager) Register(service *Service) error {
m.mutex.Lock()
defer m.mutex.Unlock()
// 验证服务信息
if service.Name == "" {
return fmt.Errorf("服务名称不能为空")
}
// 存储服务信息
m.services[service.Name] = service
// 注册到注册中心
if err := m.registrar.Register(m.ctx, service); err != nil {
return fmt.Errorf("注册服务失败: %s", err.Error())
}
// 启动健康检查
m.wg.Add(1)
go m.healthCheck(service)
return nil
}
// 注销服务
func (m *ServiceRegistryManager) Deregister(serviceName string) error {
m.mutex.Lock()
defer m.mutex.Unlock()
service, exists := m.services[serviceName]
if !exists {
return fmt.Errorf("服务不存在: %s", serviceName)
}
// 从注册中心注销
if err := m.registrar.Deregister(m.ctx, service); err != nil {
return fmt.Errorf("注销服务失败: %s", err.Error())
}
// 删除本地缓存
delete(m.services, serviceName)
delete(m.instances, serviceName)
return nil
}
// 发现服务
func (m *ServiceRegistryManager) Discover(serviceName string) ([]*ServiceInstance, error) {
m.mutex.RLock()
instances, exists := m.instances[serviceName]
m.mutex.RUnlock()
if exists && len(instances) > 0 {
return instances, nil
}
// 从注册中心获取
serviceInstances, err := m.discovery.GetService(m.ctx, serviceName)
if err != nil {
return nil, fmt.Errorf("发现服务失败: %s", err.Error())
}
// 更新本地缓存
m.mutex.Lock()
m.instances[serviceName] = serviceInstances
m.mutex.Unlock()
return serviceInstances, nil
}
// 监听服务变更
func (m *ServiceRegistryManager) Watch(serviceName string) (Watcher, error) {
return m.discovery.Watch(m.ctx, serviceName)
}
// 健康检查
func (m *ServiceRegistryManager) healthCheck(service *Service) {
defer m.wg.Done()
ticker := time.NewTicker(m.config.HealthCheckInterval)
defer ticker.Stop()
for {
select {
case <-ticker.C:
if err := m.performHealthCheck(service); err != nil {
fmt.Printf("健康检查失败: %s\n", err.Error())
}
case <-m.ctx.Done():
return
}
}
}
// 执行健康检查
func (m *ServiceRegistryManager) performHealthCheck(service *Service) error {
// 遍历服务端点进行健康检查
for _, endpoint := range service.Endpoints {
if err := m.checkEndpoint(endpoint); err != nil {
return fmt.Errorf("端点健康检查失败 %s: %s", endpoint, err.Error())
}
}
return nil
}
// 检查端点健康状态
func (m *ServiceRegistryManager) checkEndpoint(endpoint string) error {
// 简化的HTTP健康检查
// 实际实现应该支持多种检查方式
timeout := 5 * time.Second
client := &http.Client{Timeout: timeout}
resp, err := client.Get(endpoint + "/health")
if err != nil {
return err
}
defer resp.Body.Close()
if resp.StatusCode >= 200 && resp.StatusCode < 300 {
return nil
}
return fmt.Errorf("健康检查失败: HTTP %d", resp.StatusCode)
}
// 获取服务信息
func (m *ServiceRegistryManager) GetService(serviceName string) (*Service, bool) {
m.mutex.RLock()
defer m.mutex.RUnlock()
service, exists := m.services[serviceName]
return service, exists
}
// 获取所有服务
func (m *ServiceRegistryManager) GetAllServices() map[string]*Service {
m.mutex.RLock()
defer m.mutex.RUnlock()
services := make(map[string]*Service)
for k, v := range m.services {
services[k] = v
}
return services
}
// 关闭注册管理器
func (m *ServiceRegistryManager) Close() error {
m.cancel()
m.wg.Wait()
// 注销所有服务
for serviceName := range m.services {
if err := m.Deregister(serviceName); err != nil {
fmt.Printf("注销服务失败 %s: %s\n", serviceName, err.Error())
}
}
return nil
}
// Consul注册器实现
type ConsulRegistry struct {
client *consul.Client
config *RegistryConfig
serviceID string
checkID string
}
// 创建Consul注册器
func NewConsulRegistry(config *RegistryConfig) (*ConsulRegistry, error) {
consulConfig := consul.DefaultConfig()
if len(config.Address) > 0 {
consulConfig.Address = config.Address[0]
}
if config.Timeout > 0 {
consulConfig.HttpClient.Timeout = config.Timeout
}
client, err := consul.NewClient(consulConfig)
if err != nil {
return nil, fmt.Errorf("创建Consul客户端失败: %s", err.Error())
}
return &ConsulRegistry{
client: client,
config: config,
}, nil
}
// 注册服务到Consul
func (c *ConsulRegistry) Register(ctx context.Context, service *Service) error {
registration := &consul.AgentServiceRegistration{
ID: generateServiceID(service),
Name: service.Name,
Tags: []string{service.Version},
Meta: service.Metadata,
Address: getLocalIP(),
}
// 添加服务端口
if len(service.Endpoints) > 0 {
host, port, err := parseEndpoint(service.Endpoints[0])
if err == nil {
registration.Address = host
registration.Port = port
}
}
// 添加健康检查
if len(service.Endpoints) > 0 {
registration.Check = &consul.AgentServiceCheck{
HTTP: service.Endpoints[0] + "/health",
Interval: c.config.HealthCheckInterval.String(),
Timeout: "5s",
DeregisterCriticalServiceAfter: c.config.DeregisterCritical,
}
}
return c.client.Agent().ServiceRegister(registration)
}
// 从Consul注销服务
func (c *ConsulRegistry) Deregister(ctx context.Context, service *Service) error {
serviceID := generateServiceID(service)
return c.client.Agent().ServiceDeregister(serviceID)
}
// 从Consul发现服务
func (c *ConsulRegistry) GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error) {
services, _, err := c.client.Health().Service(serviceName, "", true, nil)
if err != nil {
return nil, fmt.Errorf("查询Consul服务失败: %s", err.Error())
}
instances := make([]*ServiceInstance, 0, len(services))
for _, service := range services {
instance := &ServiceInstance{
ID: service.Service.ID,
Name: service.Service.Service,
Version: c.getServiceVersion(service.Service.Tags),
Address: service.Service.Address,
Port: service.Service.Port,
Metadata: service.Service.Meta,
}
instances = append(instances, instance)
}
return instances, nil
}
// 监听Consul服务变更
func (c *ConsulRegistry) Watch(ctx context.Context, serviceName string) (Watcher, error) {
return NewConsulWatcher(c.client, serviceName), nil
}
// 生成服务ID
func generateServiceID(service *Service) string {
return fmt.Sprintf("%s-%s-%s", service.Name, service.Version, getLocalIP())
}
// 获取本地IP
func getLocalIP() string {
addrs, err := net.InterfaceAddrs()
if err != nil {
return "127.0.0.1"
}
for _, addr := range addrs {
if ipNet, ok := addr.(*net.IPNet); ok && !ipNet.IP.IsLoopback() {
if ipNet.IP.To4() != nil {
return ipNet.IP.String()
}
}
}
return "127.0.0.1"
}
// 解析端点
func parseEndpoint(endpoint string) (string, int, error) {
parts := strings.Split(endpoint, ":")
if len(parts) < 2 {
return "", 0, fmt.Errorf("无效的端点格式: %s", endpoint)
}
port, err := strconv.Atoi(parts[len(parts)-1])
if err != nil {
return "", 0, fmt.Errorf("无效的端口号: %s", parts[len(parts)-1])
}
host := strings.Join(parts[:len(parts)-1], ":")
return host, port, nil
}
// 获取服务版本
func (c *ConsulRegistry) getServiceVersion(tags []string) string {
if len(tags) > 0 {
return tags[0]
}
return "latest"
}
// Consul监听器实现
type ConsulWatcher struct {
client *consul.Client
serviceName string
lastIndex uint64
stopCh chan struct{}
}
// 创建Consul监听器
func NewConsulWatcher(client *consul.Client, serviceName string) *ConsulWatcher {
return &ConsulWatcher{
client: client,
serviceName: serviceName,
stopCh: make(chan struct{}),
}
}
// 下一个变更事件
func (w *ConsulWatcher) Next() ([]*ServiceInstance, error) {
for {
select {
case <-w.stopCh:
return nil, fmt.Errorf("监听器已停止")
default:
queryOptions := &consul.QueryOptions{
WaitIndex: w.lastIndex,
WaitTime: 30 * time.Second,
}
services, meta, err := w.client.Health().Service(w.serviceName, "", true, queryOptions)
if err != nil {
return nil, fmt.Errorf("查询服务失败: %s", err.Error())
}
// 检查是否有更新
if meta.LastIndex > w.lastIndex {
w.lastIndex = meta.LastIndex
return w.convertServices(services), nil
}
}
}
}
// 停止监听
func (w *ConsulWatcher) Stop() error {
close(w.stopCh)
return nil
}
// 转换服务列表
func (w *ConsulWatcher) convertServices(consulServices []*consul.ServiceEntry) []*ServiceInstance {
instances := make([]*ServiceInstance, 0, len(consulServices))
for _, service := range consulServices {
instance := &ServiceInstance{
ID: service.Service.ID,
Name: service.Service.Service,
Address: service.Service.Address,
Port: service.Service.Port,
Metadata: service.Service.Meta,
}
if len(service.Service.Tags) > 0 {
instance.Version = service.Service.Tags[0]
}
instances = append(instances, instance)
}
return instances
}
---
02.负载均衡算法
a.轮询算法
a.简单轮询
依次轮询所有可用的服务实例。
b.加权轮询
根据实例权重分配请求。
b.随机算法
a.简单随机
随机选择一个服务实例。
b.加权随机
根据权重进行随机选择。
c.最少连接算法
a.动态最少连接
选择当前连接数最少的实例。
b.加权最少连接
结合权重和连接数进行选择。
d.一致性哈希算法
a.哈希环
使用一致性哈希环分配请求。
b.虚拟节点
通过虚拟节点提高分布均匀性。
e.负载均衡示例
---
// 负载均衡算法实现示例
package balancer
import (
"fmt"
"hash/crc32"
"math/rand"
"sort"
"sync"
"time"
)
// 负载均衡器接口
type LoadBalancer interface {
// 选择服务实例
Choose(instances []*ServiceInstance) *ServiceInstance
// 更新权重
UpdateWeight(instanceID string, weight int)
// 移除实例
RemoveInstance(instanceID string)
}
// 轮询负载均衡器
type RoundRobinBalancer struct {
instances []*ServiceInstance
currentIndex int
mutex sync.RWMutex
}
// 创建轮询负载均衡器
func NewRoundRobinBalancer() *RoundRobinBalancer {
return &RoundRobinBalancer{
instances: make([]*ServiceInstance, 0),
currentIndex: 0,
}
}
// 选择实例
func (b *RoundRobinBalancer) Choose(instances []*ServiceInstance) *ServiceInstance {
b.mutex.Lock()
defer b.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 更新实例列表
b.instances = instances
// 轮询选择
instance := b.instances[b.currentIndex]
b.currentIndex = (b.currentIndex + 1) % len(b.instances)
return instance
}
// 更新权重（轮询算法不支持权重）
func (b *RoundRobinBalancer) UpdateWeight(instanceID string, weight int) {
// 轮询算法不使用权重，忽略更新
}
// 移除实例
func (b *RoundRobinBalancer) RemoveInstance(instanceID string) {
b.mutex.Lock()
defer b.mutex.Unlock()
for i, instance := range b.instances {
if instance.ID == instanceID {
b.instances = append(b.instances[:i], b.instances[i+1:]...)
// 调整当前索引
if b.currentIndex >= len(b.instances) && len(b.instances) > 0 {
b.currentIndex = 0
}
break
}
}
}
// 加权轮询负载均衡器
type WeightedRoundRobinBalancer struct {
instances []*WeightedInstance
mutex sync.RWMutex
}
// 带权重的实例
type WeightedInstance struct {
*ServiceInstance
weight int
currentWeight int
}
// 创建加权轮询负载均衡器
func NewWeightedRoundRobinBalancer() *WeightedRoundRobinBalancer {
return &WeightedRoundRobinBalancer{
instances: make([]*WeightedInstance, 0),
}
}
// 选择实例
func (b *WeightedRoundRobinBalancer) Choose(instances []*ServiceInstance) *ServiceInstance {
b.mutex.Lock()
defer b.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 转换为带权重的实例
b.updateInstances(instances)
if len(b.instances) == 0 {
return nil
}
// 计算总权重
totalWeight := 0
for _, instance := range b.instances {
totalWeight += instance.weight
}
// 选择实例
var selected *WeightedInstance
maxCurrentWeight := -1
for _, instance := range b.instances {
instance.currentWeight += instance.weight
if instance.currentWeight > maxCurrentWeight {
maxCurrentWeight = instance.currentWeight
selected = instance
}
}
if selected != nil {
selected.currentWeight -= totalWeight
return selected.ServiceInstance
}
return nil
}
// 更新实例列表
func (b *WeightedRoundRobinBalancer) updateInstances(instances []*ServiceInstance) {
// 创建新的实例映射
instanceMap := make(map[string]*ServiceInstance)
for _, instance := range instances {
instanceMap[instance.ID] = instance
}
// 更新现有实例或添加新实例
for _, weightedInstance := range b.instances {
if newInstance, exists := instanceMap[weightedInstance.ID]; exists {
weightedInstance.ServiceInstance = newInstance
delete(instanceMap, weightedInstance.ID)
}
}
// 添加新实例
for _, instance := range instanceMap {
weight := b.extractWeight(instance.Metadata)
weightedInstance := &WeightedInstance{
ServiceInstance: instance,
weight: weight,
currentWeight: 0,
}
b.instances = append(b.instances, weightedInstance)
}
// 移除不存在的实例
var newInstances []*WeightedInstance
for _, weightedInstance := range b.instances {
if _, exists := instanceMap[weightedInstance.ID]; exists || len(instanceMap) == 0 {
newInstances = append(newInstances, weightedInstance)
}
}
b.instances = newInstances
}
// 提取权重
func (b *WeightedRoundRobinBalancer) extractWeight(metadata map[string]string) int {
if weightStr, exists := metadata["weight"]; exists {
if weight, err := strconv.Atoi(weightStr); err == nil {
return weight
}
}
return 1 // 默认权重
}
// 更新权重
func (b *WeightedRoundRobinBalancer) UpdateWeight(instanceID string, weight int) {
b.mutex.Lock()
defer b.mutex.Unlock()
for _, instance := range b.instances {
if instance.ID == instanceID {
instance.weight = weight
break
}
}
}
// 移除实例
func (b *WeightedRoundRobinBalancer) RemoveInstance(instanceID string) {
b.mutex.Lock()
defer b.mutex.Unlock()
for i, instance := range b.instances {
if instance.ID == instanceID {
b.instances = append(b.instances[:i], b.instances[i+1:]...)
break
}
}
}
// 随机负载均衡器
type RandomBalancer struct {
instances []*ServiceInstance
mutex sync.RWMutex
rand *rand.Rand
}
// 创建随机负载均衡器
func NewRandomBalancer() *RandomBalancer {
return &RandomBalancer{
instances: make([]*ServiceInstance, 0),
rand: rand.New(rand.NewSource(time.Now().UnixNano())),
}
}
// 选择实例
func (b *RandomBalancer) Choose(instances []*ServiceInstance) *ServiceInstance {
b.mutex.Lock()
defer b.mutex.Unlock()
if len(instances) == 0 {
return nil
}
b.instances = instances
index := b.rand.Intn(len(instances))
return instances[index]
}
// 更新权重
func (b *RandomBalancer) UpdateWeight(instanceID string, weight int) {
// 随机算法不使用权重，忽略更新
}
// 移除实例
func (b *RandomBalancer) RemoveInstance(instanceID string) {
b.mutex.Lock()
defer b.mutex.Unlock()
for i, instance := range b.instances {
if instance.ID == instanceID {
b.instances = append(b.instances[:i], b.instances[i+1:]...)
break
}
}
}
// 加权随机负载均衡器
type WeightedRandomBalancer struct {
instances []*WeightedInstance
mutex sync.RWMutex
rand *rand.Rand
}
// 创建加权随机负载均衡器
func NewWeightedRandomBalancer() *WeightedRandomBalancer {
return &WeightedRandomBalancer{
instances: make([]*WeightedInstance, 0),
rand: rand.New(rand.NewSource(time.Now().UnixNano())),
}
}
// 选择实例
func (b *WeightedRandomBalancer) Choose(instances []*ServiceInstance) *ServiceInstance {
b.mutex.Lock()
defer b.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 转换为带权重的实例
b.updateInstances(instances)
if len(b.instances) == 0 {
return nil
}
// 计算总权重
totalWeight := 0
for _, instance := range b.instances {
totalWeight += instance.weight
}
if totalWeight <= 0 {
return nil
}
// 根据权重随机选择
randomValue := b.rand.Intn(totalWeight)
currentWeight := 0
for _, instance := range b.instances {
currentWeight += instance.weight
if randomValue < currentWeight {
return instance.ServiceInstance
}
}
return b.instances[0].ServiceInstance
}
// 一致性哈希负载均衡器
type ConsistentHashBalancer struct {
instances []*ServiceInstance
hashRing *HashRing
mutex sync.RWMutex
virtualNodes int
}
// 哈希环
type HashRing struct {
nodes []uint32
nodeMap map[uint32]*ServiceInstance
}
// 创建哈希环
func NewHashRing() *HashRing {
return &HashRing{
nodes: make([]uint32, 0),
nodeMap: make(map[uint32]*ServiceInstance),
}
}
// 添加节点
func (r *HashRing) Add(node *ServiceInstance, virtualNodes int) {
for i := 0; i < virtualNodes; i++ {
virtualKey := fmt.Sprintf("%s:%d", node.ID, i)
hash := crc32.ChecksumIEEE([]byte(virtualKey))
r.nodes = append(r.nodes, hash)
r.nodeMap[hash] = node
}
sort.Slice(r.nodes, func(i, j int) bool {
return r.nodes[i] < r.nodes[j]
})
}
// 移除节点
func (r *HashRing) Remove(node *ServiceInstance, virtualNodes int) {
for i := 0; i < virtualNodes; i++ {
virtualKey := fmt.Sprintf("%s:%d", node.ID, i)
hash := crc32.ChecksumIEEE([]byte(virtualKey))
delete(r.nodeMap, hash)
// 从节点列表中移除
for j, nodeHash := range r.nodes {
if nodeHash == hash {
r.nodes = append(r.nodes[:j], r.nodes[j+1:]...)
break
}
}
}
}
// 获取节点
func (r *HashRing) Get(key string) *ServiceInstance {
if len(r.nodes) == 0 {
return nil
}
hash := crc32.ChecksumIEEE([]byte(key))
// 查找第一个大于等于hash的节点
for _, nodeHash := range r.nodes {
if nodeHash >= hash {
return r.nodeMap[nodeHash]
}
}
// 环绕到第一个节点
return r.nodeMap[r.nodes[0]]
}
// 创建一致性哈希负载均衡器
func NewConsistentHashBalancer(virtualNodes int) *ConsistentHashBalancer {
if virtualNodes <= 0 {
virtualNodes = 150 // 默认虚拟节点数
}
return &ConsistentHashBalancer{
instances: make([]*ServiceInstance, 0),
hashRing: NewHashRing(),
virtualNodes: virtualNodes,
}
}
// 选择实例（需要一个key来计算哈希）
func (b *ConsistentHashBalancer) Choose(key string, instances []*ServiceInstance) *ServiceInstance {
b.mutex.Lock()
defer b.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 更新哈希环
b.updateHashRing(instances)
if len(b.hashRing.nodes) == 0 {
return nil
}
return b.hashRing.Get(key)
}
// 更新哈希环
func (b *ConsistentHashBalancer) updateHashRing(instances []*ServiceInstance) {
// 创建新的哈希环
newRing := NewHashRing()
// 添加所有实例
for _, instance := range instances {
newRing.Add(instance, b.virtualNodes)
}
b.hashRing = newRing
}
// 更新权重（一致性哈希不直接支持权重）
func (b *ConsistentHashBalancer) UpdateWeight(instanceID string, weight int) {
// 可以通过调整虚拟节点数量来模拟权重
// 这里简化处理，不实现
}
// 移除实例
func (b *ConsistentHashBalancer) RemoveInstance(instanceID string) {
b.mutex.Lock()
defer b.mutex.Unlock()
for i, instance := range b.instances {
if instance.ID == instanceID {
b.instances = append(b.instances[:i], b.instances[i+1:]...)
break
}
}
// 重新构建哈希环
b.updateHashRing(b.instances)
}
---
2.9 中间件系统组件 Middleware
01.中间件系统架构
a.中间件链式架构
a.链式处理模式
支持多个中间件的链式组合和处理。
b.上下文传递
在中间件链中安全传递请求上下文和元数据。
c.错误传播
统一的错误处理和错误传播机制。
d.生命周期管理
中间件的生命周期管理和资源清理。
b.中间件接口设计
a.Middleware接口
定义中间件的基本操作接口。
b.Handler接口
定义请求处理器接口。
c.Chain接口
定义中间件链管理接口。
c.中间件系统示例
---
// Middleware中间件系统架构示例
package middleware
import (
"context"
"fmt"
"net/http"
"time"
"github.com/go-kratos/kratos/v2/middleware"
)
// 中间件接口
type Middleware interface {
// 处理请求
Process(ctx context.Context, req Request, next Handler) (Response, error)
}
// 处理器接口
type Handler interface {
// 处理请求
Handle(ctx context.Context, req Request) (Response, error)
}
// 中间件函数类型
type MiddlewareFunc func(Handler) Handler
// 实现Middleware接口
func (f MiddlewareFunc) Process(ctx context.Context, req Request, next Handler) (Response, error) {
return f(next).Handle(ctx, req)
}
// 请求抽象
type Request struct {
Header http.Header
Body []byte
Method string
Path string
Query map[string][]string
Context context.Context
Metadata map[string]interface{}
RemoteAddr string
UserAgent string
StartTime time.Time
}
// 响应抽象
type Response struct {
Header http.Header
Body []byte
Status int
Size int
}
// 中间件链
type MiddlewareChain struct {
middlewares []Middleware
handler Handler
}
// 创建中间件链
func NewChain(handler Handler, middlewares ...Middleware) *MiddlewareChain {
return &MiddlewareChain{
middlewares: middlewares,
handler: handler,
}
}
// 执行中间件链
func (c *MiddlewareChain) Execute(ctx context.Context, req Request) (Response, error) {
var handler Handler = c.handler
// 反向构建中间件链
for i := len(c.middlewares) - 1; i >= 0; i-- {
middleware := c.middlewares[i]
currentHandler := handler
handler = HandlerFunc(func(ctx context.Context, req Request) (Response, error) {
return middleware.Process(ctx, req, currentHandler)
})
}
return handler.Handle(ctx, req)
}
// 处理器函数
type HandlerFunc func(ctx context.Context, req Request) (Response, error)
// 实现Handler接口
func (f HandlerFunc) Handle(ctx context.Context, req Request) (Response, error) {
return f(ctx, req)
}
// 中间件管理器
type MiddlewareManager struct {
middlewares map[string]Middleware
chains map[string]*MiddlewareChain
mutex sync.RWMutex
}
// 创建中间件管理器
func NewMiddlewareManager() *MiddlewareManager {
return &MiddlewareManager{
middlewares: make(map[string]Middleware),
chains: make(map[string]*MiddlewareChain),
}
}
// 注册中间件
func (m *MiddlewareManager) Register(name string, middleware Middleware) error {
m.mutex.Lock()
defer m.mutex.Unlock()
if _, exists := m.middlewares[name]; exists {
return fmt.Errorf("中间件已存在: %s", name)
}
m.middlewares[name] = middleware
return nil
}
// 获取中间件
func (m *MiddlewareManager) Get(name string) (Middleware, bool) {
m.mutex.RLock()
defer m.mutex.RUnlock()
middleware, exists := m.middlewares[name]
return middleware, exists
}
// 创建中间件链
func (m *MiddlewareManager) CreateChain(name string, handler Handler, middlewareNames ...string) error {
m.mutex.Lock()
defer m.mutex.Unlock()
var middlewares []Middleware
for _, name := range middlewareNames {
middleware, exists := m.middlewares[name]
if !exists {
return fmt.Errorf("中间件不存在: %s", name)
}
middlewares = append(middlewares, middleware)
}
m.chains[name] = NewChain(handler, middlewares...)
return nil
}
// 执行中间件链
func (m *MiddlewareManager) ExecuteChain(ctx context.Context, chainName string, req Request) (Response, error) {
m.mutex.RLock()
chain, exists := m.chains[chainName]
m.mutex.RUnlock()
if !exists {
return Response{}, fmt.Errorf("中间件链不存在: %s", chainName)
}
return chain.Execute(ctx, req)
}
// 获取所有中间件名称
func (m *MiddlewareManager) List() []string {
m.mutex.RLock()
defer m.mutex.RUnlock()
names := make([]string, 0, len(m.middlewares))
for name := range m.middlewares {
names = append(names, name)
}
return names
}
// 中间件工厂
type MiddlewareFactory struct{}
// 创建日志中间件
func (f *MiddlewareFactory) CreateLoggingMiddleware(logger Logger) Middleware {
return &LoggingMiddleware{logger: logger}
}
// 创建认证中间件
func (f *MiddlewareFactory) CreateAuthMiddleware(authProvider AuthProvider) Middleware {
return &AuthMiddleware{authProvider: authProvider}
}
// 创建限流中间件
func (f *MiddlewareFactory) CreateRateLimitMiddleware(config *RateLimitConfig) Middleware {
return NewRateLimitMiddleware(config)
}
// 创建熔断中间件
func (f *MiddlewareFactory) CreateCircuitBreakerMiddleware(config *CircuitBreakerConfig) Middleware {
return NewCircuitBreakerMiddleware(config)
}
// 日志中间件
type LoggingMiddleware struct {
logger Logger
}
// 处理请求
func (m *LoggingMiddleware) Process(ctx context.Context, req Request, next Handler) (Response, error) {
start := time.Now()
// 记录请求开始
m.logger.Infof("开始处理请求: %s %s", req.Method, req.Path)
// 执行下一个处理器
resp, err := next.Handle(ctx, req)
// 记录请求完成
duration := time.Since(start)
if err != nil {
m.logger.Errorf("请求处理失败: %s %s, 耗时: %v, 错误: %v", req.Method, req.Path, duration, err)
} else {
m.logger.Infof("请求处理完成: %s %s, 耗时: %v, 状态码: %d", req.Method, req.Path, duration, resp.Status)
}
return resp, err
}
// 认证中间件
type AuthMiddleware struct {
authProvider AuthProvider
}
// 处理请求
func (m *AuthMiddleware) Process(ctx context.Context, req Request, next Handler) (Response, error) {
// 检查是否跳过认证
if m.shouldSkipAuth(req.Path) {
return next.Handle(ctx, req)
}
// 获取认证令牌
token := m.extractToken(req)
if token == "" {
return Response{Status: http.StatusUnauthorized}, fmt.Errorf("缺少认证令牌")
}
// 验证令牌
claims, err := m.authProvider.ValidateToken(token)
if err != nil {
return Response{Status: http.StatusUnauthorized}, fmt.Errorf("无效令牌: %s", err.Error())
}
// 将用户信息添加到上下文
ctx = context.WithValue(ctx, "user_id", claims.UserID)
ctx = context.WithValue(ctx, "user_role", claims.Role)
return next.Handle(ctx, req)
}
// 检查是否跳过认证
func (m *AuthMiddleware) shouldSkipAuth(path string) bool {
skipPaths := []string{
"/health",
"/ready",
"/metrics",
"/api/v1/auth/login",
"/api/v1/auth/register",
}
for _, skipPath := range skipPaths {
if path == skipPath {
return true
}
}
return false
}
// 提取令牌
func (m *AuthMiddleware) extractToken(req Request) string {
// 从Header提取
authHeader := req.Header.Get("Authorization")
if authHeader != "" {
parts := strings.SplitN(authHeader, " ", 2)
if len(parts) == 2 && strings.ToLower(parts[0]) == "bearer" {
return parts[1]
}
}
// 从查询参数提取
if tokens, exists := req.Query["token"]; exists && len(tokens) > 0 {
return tokens[0]
}
return ""
}
// 限流中间件
type RateLimitMiddleware struct {
limiter *RateLimiter
}
// 限流器
type RateLimiter struct {
requests map[string]*TokenBucket
mutex sync.RWMutex
config *RateLimitConfig
}
// 令牌桶
type TokenBucket struct {
capacity int
tokens int
rate time.Duration
lastRefill time.Time
mutex sync.Mutex
}
// 创建限流中间件
func NewRateLimitMiddleware(config *RateLimitConfig) *RateLimitMiddleware {
return &RateLimitMiddleware{
limiter: NewRateLimiter(config),
}
}
// 处理请求
func (m *RateLimitMiddleware) Process(ctx context.Context, req Request, next Handler) (Response, error) {
// 获取客户端标识
clientID := m.getClientID(req)
// 检查限流
if !m.limiter.Allow(clientID) {
return Response{
Status: http.StatusTooManyRequests,
Body: []byte(`{"error": "请求过于频繁，请稍后重试"}`),
Header: http.Header{"Content-Type": []string{"application/json"}},
}, nil
}
return next.Handle(ctx, req)
}
// 获取客户端ID
func (m *RateLimitMiddleware) getClientID(req Request) string {
// 优先使用用户ID
if userID := req.Context.Value("user_id"); userID != nil {
return fmt.Sprintf("user:%v", userID)
}
// 使用IP地址
if req.RemoteAddr != "" {
return fmt.Sprintf("ip:%s", req.RemoteAddr)
}
return "unknown"
}
// 创建限流器
func NewRateLimiter(config *RateLimitConfig) *RateLimiter {
return &RateLimiter{
requests: make(map[string]*TokenBucket),
config: config,
}
}
// 允许请求
func (l *RateLimiter) Allow(clientID string) bool {
bucket := l.getBucket(clientID)
return bucket.consume(1)
}
// 获取令牌桶
func (l *RateLimiter) getBucket(clientID string) *TokenBucket {
l.mutex.RLock()
bucket, exists := l.requests[clientID]
l.mutex.RUnlock()
if !exists {
l.mutex.Lock()
// 双重检查
if bucket, exists = l.requests[clientID]; !exists {
bucket = &TokenBucket{
capacity: l.config.Capacity,
tokens: l.config.Capacity,
rate: l.config.Rate,
lastRefill: time.Now(),
}
l.requests[clientID] = bucket
}
l.mutex.Unlock()
}
return bucket
}
// 消费令牌
func (b *TokenBucket) consume(tokens int) bool {
b.mutex.Lock()
defer b.mutex.Unlock()
b.refill()
if b.tokens >= tokens {
b.tokens -= tokens
return true
}
return false
}
// 补充令牌
func (b *TokenBucket) refill() {
now := time.Now()
elapsed := now.Sub(b.lastRefill)
// 计算应该补充的令牌数
tokensToAdd := int(elapsed / b.rate)
if tokensToAdd > 0 {
b.tokens = min(b.capacity, b.tokens+tokensToAdd)
b.lastRefill = now
}
}
// 熔断中间件
type CircuitBreakerMiddleware struct {
breakers map[string]*CircuitBreaker
mutex sync.RWMutex
config *CircuitBreakerConfig
}
// 熔断器
type CircuitBreaker struct {
name string
maxRequests uint32
interval time.Duration
timeout time.Duration
readyToTrip func(counts CircuitBreakerCounts) bool
onStateChange func(name string, from, to CircuitBreakerState)
counts CircuitBreakerCounts
state CircuitBreakerState
generation uint64
mutex sync.Mutex
}
// 熔断器状态
type CircuitBreakerState int
const (
CircuitBreakerClosed CircuitBreakerState = iota
CircuitBreakerHalfOpen
CircuitBreakerOpen
)
// 熔断器计数
type CircuitBreakerCounts struct {
Requests uint32
TotalSuccesses uint32
TotalFailures uint32
ConsecutiveSuccesses uint32
ConsecutiveFailures uint32
}
// 创建熔断中间件
func NewCircuitBreakerMiddleware(config *CircuitBreakerConfig) *CircuitBreakerMiddleware {
return &CircuitBreakerMiddleware{
breakers: make(map[string]*CircuitBreaker),
config: config,
}
}
// 处理请求
func (m *CircuitBreakerMiddleware) Process(ctx context.Context, req Request, next Handler) (Response, error) {
key := m.getCircuitBreakerKey(req.Method, req.Path)
breaker := m.getOrCreateBreaker(key)
// 执行请求
var resp Response
var err error
result, circuitErr := breaker.Execute(func() (interface{}, error) {
resp, err = next.Handle(ctx, req)
return resp, err
})
if circuitErr != nil {
return Response{Status: http.StatusServiceUnavailable}, circuitErr
}
return result.(Response), err
}
// 获取熔断器键
func (m *CircuitBreakerMiddleware) getCircuitBreakerKey(method, path string) string {
return fmt.Sprintf("%s:%s", method, path)
}
// 获取或创建熔断器
func (m *CircuitBreakerMiddleware) getOrCreateBreaker(key string) *CircuitBreaker {
m.mutex.RLock()
breaker, exists := m.breakers[key]
m.mutex.RUnlock()
if exists {
return breaker
}
m.mutex.Lock()
defer m.mutex.Unlock()
// 双重检查
if breaker, exists = m.breakers[key]; exists {
return breaker
}
breaker = &CircuitBreaker{
name: key,
maxRequests: m.config.MaxRequests,
interval: m.config.Interval,
timeout: m.config.Timeout,
readyToTrip: m.config.ReadyToTrip,
onStateChange: func(name string, from, to CircuitBreakerState) {
log.Printf("熔断器状态变更: %s %s -> %s", name, from, to)
},
}
m.breakers[key] = breaker
return breaker
}
// 执行熔断器操作
func (cb *CircuitBreaker) Execute(req func() (interface{}, error)) (interface{}, error) {
generation, err := cb.beforeRequest()
if err != nil {
return nil, err
}
defer cb.afterRequest(generation, err == nil)
return req()
}
// 请求前处理
func (cb *CircuitBreaker) beforeRequest() (uint64, error) {
cb.mutex.Lock()
defer cb.mutex.Unlock()
now := time.Now()
state, generation := cb.currentState(now)
if state == CircuitBreakerOpen {
return generation, fmt.Errorf("熔断器开启")
}
cb.counts.Requests++
return generation, nil
}
// 请求后处理
func (cb *CircuitBreaker) afterRequest(before uint64, success bool) {
cb.mutex.Lock()
defer cb.mutex.Unlock()
now := time.Now()
state, generation := cb.currentState(now)
if generation != before {
return
}
if success {
cb.onSuccess(state, now)
} else {
cb.onFailure(state, now)
}
}
// 成功处理
func (cb *CircuitBreaker) onSuccess(state CircuitBreakerState, now time.Time) {
cb.counts.TotalSuccesses++
cb.counts.ConsecutiveSuccesses++
cb.counts.ConsecutiveFailures = 0
if state == CircuitBreakerHalfOpen && cb.counts.ConsecutiveSuccesses >= cb.maxRequests {
cb.setState(CircuitBreakerClosed, now)
}
}
// 失败处理
func (cb *CircuitBreaker) onFailure(state CircuitBreakerState, now time.Time) {
cb.counts.TotalFailures++
cb.counts.ConsecutiveFailures++
cb.counts.ConsecutiveSuccesses = 0
if cb.readyToTrip(cb.counts) {
cb.setState(CircuitBreakerOpen, now)
}
}
// 获取当前状态
func (cb *CircuitBreaker) currentState(now time.Time) (CircuitBreakerState, uint64) {
switch cb.state {
case CircuitBreakerClosed:
if !cb.expiry.IsZero() && cb.expiry.Before(now) {
cb.toNewGeneration(now)
}
case CircuitBreakerOpen:
if cb.expiry.Before(now) {
cb.setState(CircuitBreakerHalfOpen, now)
}
}
return cb.state, cb.generation
}
// 设置状态
func (cb *CircuitBreaker) setState(state CircuitBreakerState, now time.Time) {
if cb.state == state {
return
}
prev := cb.state
cb.state = state
cb.toNewGeneration(now)
if cb.onStateChange != nil {
cb.onStateChange(cb.name, prev, state)
}
}
// 创建新世代
func (cb *CircuitBreaker) toNewGeneration(now time.Time) {
cb.generation++
cb.counts = CircuitBreakerCounts{}
var zero time.Time
switch cb.state {
case CircuitBreakerClosed:
if cb.interval == 0 {
cb.expiry = zero
} else {
cb.expiry = now.Add(cb.interval)
}
case CircuitBreakerOpen:
cb.expiry = now.Add(cb.timeout)
default: // CircuitBreakerHalfOpen
cb.expiry = zero
}
}
---
02.核心中间件实现
a.日志中间件
a.请求日志
记录HTTP请求的详细信息。
b.响应日志
记录HTTP响应的详细信息。
c.错误日志
记录处理过程中的错误信息。
b.认证中间件
a.JWT认证
支持JWT令牌的验证和解析。
b.OAuth2认证
支持OAuth2认证流程。
c.API Key认证
支持API Key认证方式。
c.授权中间件
a.RBAC权限控制
基于角色的访问控制。
b.ABAC权限控制
基于属性的访问控制。
c.权限检查
检查用户是否有权限访问资源。
d.限流中间件
a.基于IP限流
根据客户端IP进行限流。
b.基于用户限流
根据用户ID进行限流。
c.基于接口限流
根据API接口进行限流。
e.熔断中间件
a.错误率熔断
根据错误率进行熔断。
b.响应时间熔断
根据响应时间进行熔断。
c.手动熔断
支持手动触发熔断。
f.中间件配置示例
---
// 中间件配置示例
package config
import "time"
// 限流配置
type RateLimitConfig struct {
Capacity int `json:"capacity"` // 令牌桶容量
Rate time.Duration `json:"rate"` // 令牌生成速率
Window time.Duration `json:"window"` // 时间窗口
Strategy string `json:"strategy"` // 限流策略
}
// 熔断配置
type CircuitBreakerConfig struct {
MaxRequests uint32 `json:"max_requests"` // 半开状态最大请求数
Interval time.Duration `json:"interval"` // 统计时间间隔
Timeout time.Duration `json:"timeout"` // 熔断超时时间
ReadyToTrip func(counts CircuitBreakerCounts) bool
}
// 认证配置
type AuthConfig struct {
Type string `json:"type"` // 认证类型
Secret string `json:"secret"` // 密钥
Expiry time.Duration `json:"expiry"` // 令牌过期时间
Refresh time.Duration `json:"refresh"` // 刷新令牌过期时间
SkipPaths []string `json:"skip_paths"` // 跳过认证的路径
}
// 授权配置
type AuthorizationConfig struct {
Type string `json:"type"` // 授权类型
Rules []AuthRule `json:"rules"` // 授权规则
Defaults map[string]string `json:"defaults"` // 默认权限
}
// 授权规则
type AuthRule struct {
Path string `json:"path"` // 路径模式
Methods []string `json:"methods"` // HTTP方法
Roles []string `json:"roles"` // 允许的角色
Policies []string `json:"policies"` // 策略名称
}
// 中间件配置
type MiddlewareConfig struct {
Logging LoggingConfig `json:"logging"`
RateLimit *RateLimitConfig `json:"rate_limit,omitempty"`
CircuitBreaker *CircuitBreakerConfig `json:"circuit_breaker,omitempty"`
Auth *AuthConfig `json:"auth,omitempty"`
Authorization *AuthorizationConfig `json:"authorization,omitempty"`
}
// 默认配置
func DefaultMiddlewareConfig() *MiddlewareConfig {
return &MiddlewareConfig{
Logging: LoggingConfig{
Level: "info",
Format: "json",
IncludeBody: false,
},
RateLimit: &RateLimitConfig{
Capacity: 1000,
Rate: 1 * time.Second,
Window: 1 * time.Minute,
Strategy: "token_bucket",
},
CircuitBreaker: &CircuitBreakerConfig{
MaxRequests: 5,
Interval: 60 * time.Second,
Timeout: 30 * time.Second,
ReadyToTrip: func(counts CircuitBreakerCounts) bool {
failureRatio := float64(counts.TotalFailures) / float64(counts.Requests)
return counts.Requests >= 10 && failureRatio >= 0.6
},
},
}
}
---
2.10 服务发现组件 Discovery
01.服务发现架构
a.服务发现机制
a.客户端发现
客户端直接查询注册中心获取服务实例。
b.服务端发现
客户端通过负载均衡器访问服务。
c.混合发现
结合客户端和服务端发现的优点。
b.服务实例管理
a.实例注册
服务实例启动时自动注册到发现系统。
b.健康检查
定期检查服务实例的健康状态。
c.实例注销
服务实例下线时自动注销。
c.负载均衡策略
a.静态负载均衡
使用预配置的负载均衡算法。
b.动态负载均衡
根据实时指标调整负载均衡策略。
c.故障转移
自动处理故障实例的流量转移。
d.服务发现示例
---
// Discovery服务发现架构示例
package discovery
import (
"context"
"fmt"
"sync"
"time"
"github.com/go-kratos/kratos/v2/registry"
)
// 服务发现器接口
type Discovery interface {
// 获取服务实例
GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
// 监听服务变更
Watch(ctx context.Context, serviceName string) (Watcher, error)
// 获取服务列表
ListServices(ctx context.Context) ([]string, error)
}
// 服务监听器接口
type Watcher interface {
// 下一个服务变更事件
Next() ([]*ServiceInstance, error)
// 停止监听
Stop() error
}
// 服务实例
type ServiceInstance struct {
ID string `json:"id"`
Name string `json:"name"`
Version string `json:"version"`
Address string `json:"address"`
Port int `json:"port"`
Tags []string `json:"tags"`
Metadata map[string]string `json:"metadata"`
Weight int `json:"weight"`
Healthy bool `json:"healthy"`
Enable bool `json:"enable"`
}
// 服务缓存
type ServiceCache struct {
instances map[string][]*ServiceInstance
mutex sync.RWMutex
ttl time.Duration
lastUpdate map[string]time.Time
}
// 创建服务缓存
func NewServiceCache(ttl time.Duration) *ServiceCache {
return &ServiceCache{
instances: make(map[string][]*ServiceInstance),
ttl: ttl,
lastUpdate: make(map[string]time.Time),
}
}
// 获取服务实例
func (c *ServiceCache) Get(serviceName string) ([]*ServiceInstance, bool) {
c.mutex.RLock()
defer c.mutex.RUnlock()
instances, exists := c.instances[serviceName]
if !exists {
return nil, false
}
// 检查是否过期
if lastUpdate, exists := c.lastUpdate[serviceName]; exists {
if time.Since(lastUpdate) > c.ttl {
return nil, false
}
}
return instances, true
}
// 设置服务实例
func (c *ServiceCache) Set(serviceName string, instances []*ServiceInstance) {
c.mutex.Lock()
defer c.mutex.Unlock()
c.instances[serviceName] = make([]*ServiceInstance, len(instances))
copy(c.instances[serviceName], instances)
c.lastUpdate[serviceName] = time.Now()
}
// 删除服务实例
func (c *ServiceCache) Delete(serviceName string) {
c.mutex.Lock()
defer c.mutex.Unlock()
delete(c.instances, serviceName)
delete(c.lastUpdate, serviceName)
}
// 清理过期缓存
func (c *ServiceCache) CleanExpired() {
c.mutex.Lock()
defer c.mutex.Unlock()
now := time.Now()
for serviceName, lastUpdate := range c.lastUpdate {
if now.Sub(lastUpdate) > c.ttl {
delete(c.instances, serviceName)
delete(c.lastUpdate, serviceName)
}
}
}
// 服务发现管理器
type DiscoveryManager struct {
discovery Discovery
cache *ServiceCache
watchers map[string]map[string]Watcher // serviceName -> watcherID -> Watcher
mutex sync.RWMutex
config *DiscoveryConfig
ctx context.Context
cancel context.CancelFunc
wg sync.WaitGroup
}
// 服务发现配置
type DiscoveryConfig struct {
Type string `json:"type"`
Address []string `json:"address"`
Timeout time.Duration `json:"timeout"`
RefreshInterval time.Duration `json:"refresh_interval"`
CacheTTL time.Duration `json:"cache_ttl"`
WatchEnabled bool `json:"watch_enabled"`
Username string `json:"username"`
Password string `json:"password"`
Token string `json:"token"`
}
// 创建服务发现管理器
func NewDiscoveryManager(config *DiscoveryConfig) (*DiscoveryManager, error) {
ctx, cancel := context.WithCancel(context.Background())
manager := &DiscoveryManager{
watchers: make(map[string]map[string]Watcher),
config: config,
ctx: ctx,
cancel: cancel,
}
// 初始化缓存
if config.CacheTTL > 0 {
manager.cache = NewServiceCache(config.CacheTTL)
}
// 初始化发现器
if err := manager.initDiscovery(); err != nil {
cancel()
return nil, fmt.Errorf("初始化服务发现器失败: %s", err.Error())
}
// 启动定期刷新
if config.RefreshInterval > 0 {
manager.wg.Add(1)
go manager.startRefreshLoop()
}
// 启动缓存清理
if manager.cache != nil {
manager.wg.Add(1)
go manager.startCacheCleanupLoop()
}
return manager, nil
}
// 初始化发现器
func (m *DiscoveryManager) initDiscovery() error {
switch m.config.Type {
case "consul":
discovery, err := NewConsulDiscovery(m.config)
if err != nil {
return err
}
m.discovery = discovery
case "etcd":
discovery, err := NewEtcdDiscovery(m.config)
if err != nil {
return err
}
m.discovery = discovery
case "nacos":
discovery, err := NewNacosDiscovery(m.config)
if err != nil {
return err
}
m.discovery = discovery
default:
return fmt.Errorf("不支持的服务发现类型: %s", m.config.Type)
}
return nil
}
// 获取服务实例
func (m *DiscoveryManager) GetService(serviceName string) ([]*ServiceInstance, error) {
// 优先从缓存获取
if m.cache != nil {
if instances, found := m.cache.Get(serviceName); found {
return m.filterHealthyInstances(instances), nil
}
}
// 从发现器获取
instances, err := m.discovery.GetService(m.ctx, serviceName)
if err != nil {
return nil, fmt.Errorf("获取服务失败: %s", err.Error())
}
// 更新缓存
if m.cache != nil {
m.cache.Set(serviceName, instances)
}
return m.filterHealthyInstances(instances), nil
}
// 监听服务变更
func (m *DiscoveryManager) Watch(serviceName string, callback WatchCallback) (string, error) {
watcherID := fmt.Sprintf("%s-%d", serviceName, time.Now().UnixNano())
watcher, err := m.discovery.Watch(m.ctx, serviceName)
if err != nil {
return "", fmt.Errorf("创建服务监听器失败: %s", err.Error())
}
m.mutex.Lock()
if _, exists := m.watchers[serviceName]; !exists {
m.watchers[serviceName] = make(map[string]Watcher)
}
m.watchers[serviceName][watcherID] = watcher
m.mutex.Unlock()
// 启动监听协程
m.wg.Add(1)
go m.watchService(serviceName, watcherID, watcher, callback)
return watcherID, nil
}
// 停止监听
func (m *DiscoveryManager) StopWatch(serviceName, watcherID string) error {
m.mutex.Lock()
defer m.mutex.Unlock()
if serviceWatchers, exists := m.watchers[serviceName]; exists {
if watcher, exists := serviceWatchers[watcherID]; exists {
err := watcher.Stop()
delete(serviceWatchers, watcherID)
return err
}
}
return fmt.Errorf("监听器不存在: %s/%s", serviceName, watcherID)
}
// 获取服务列表
func (m *DiscoveryManager) ListServices() ([]string, error) {
return m.discovery.ListServices(m.ctx)
}
// 监听服务变更
func (m *DiscoveryManager) watchService(serviceName, watcherID string, watcher Watcher, callback WatchCallback) {
defer m.wg.Done()
for {
select {
case <-m.ctx.Done():
return
default:
instances, err := watcher.Next()
if err != nil {
m.handleError(serviceName, watcherID, err)
return
}
// 过滤健康实例
healthyInstances := m.filterHealthyInstances(instances)
// 更新缓存
if m.cache != nil {
m.cache.Set(serviceName, healthyInstances)
}
// 调用回调
if callback != nil {
callback(serviceName, healthyInstances)
}
}
}
}
// 处理错误
func (m *DiscoveryManager) handleError(serviceName, watcherID string, err error) {
// 记录错误
fmt.Printf("服务监听错误 %s/%s: %s\n", serviceName, watcherID, err.Error())
// 移除监听器
m.mutex.Lock()
if serviceWatchers, exists := m.watchers[serviceName]; exists {
delete(serviceWatchers, watcherID)
if len(serviceWatchers) == 0 {
delete(m.watchers, serviceName)
}
}
m.mutex.Unlock()
// 尝试重新监听
if m.config.WatchEnabled {
time.Sleep(5 * time.Second)
m.rewatchService(serviceName, watcherID)
}
}
// 重新监听服务
func (m *DiscoveryManager) rewatchService(serviceName, watcherID string) {
watcher, err := m.discovery.Watch(m.ctx, serviceName)
if err != nil {
fmt.Printf("重新监听服务失败 %s: %s\n", serviceName, err.Error())
return
}
m.mutex.Lock()
if _, exists := m.watchers[serviceName]; !exists {
m.watchers[serviceName] = make(map[string]Watcher)
}
m.watchers[serviceName][watcherID] = watcher
m.mutex.Unlock()
// 重新启动监听协程
m.wg.Add(1)
go m.watchService(serviceName, watcherID, watcher, nil)
}
// 过滤健康实例
func (m *DiscoveryManager) filterHealthyInstances(instances []*ServiceInstance) []*ServiceInstance {
healthy := make([]*ServiceInstance, 0)
for _, instance := range instances {
if instance.Healthy && instance.Enable {
healthy = append(healthy, instance)
}
}
return healthy
}
// 启动定期刷新循环
func (m *DiscoveryManager) startRefreshLoop() {
defer m.wg.Done()
ticker := time.NewTicker(m.config.RefreshInterval)
defer ticker.Stop()
for {
select {
case <-ticker.C:
m.refreshServices()
case <-m.ctx.Done():
return
}
}
}
// 刷新服务
func (m *DiscoveryManager) refreshServices() {
services, err := m.discovery.ListServices(m.ctx)
if err != nil {
fmt.Printf("获取服务列表失败: %s\n", err.Error())
return
}
for _, serviceName := range services {
instances, err := m.discovery.GetService(m.ctx, serviceName)
if err != nil {
fmt.Printf("获取服务实例失败 %s: %s\n", serviceName, err.Error())
continue
}
if m.cache != nil {
m.cache.Set(serviceName, instances)
}
}
}
// 启动缓存清理循环
func (m *DiscoveryManager) startCacheCleanupLoop() {
defer m.wg.Done()
ticker := time.NewTicker(1 * time.Minute)
defer ticker.Stop()
for {
select {
case <-ticker.C:
m.cache.CleanExpired()
case <-m.ctx.Done():
return
}
}
}
// 关闭发现管理器
func (m *DiscoveryManager) Close() error {
m.cancel()
m.wg.Wait()
// 停止所有监听器
m.mutex.Lock()
defer m.mutex.Unlock()
for serviceName, serviceWatchers := range m.watchers {
for watcherID, watcher := range serviceWatchers {
watcher.Stop()
}
delete(m.watchers, serviceName)
}
return nil
}
// 监听回调函数
type WatchCallback func(serviceName string, instances []*ServiceInstance)
// Consul服务发现实现
type ConsulDiscovery struct {
client *consul.Client
config *DiscoveryConfig
}
// 创建Consul服务发现
func NewConsulDiscovery(config *DiscoveryConfig) (*ConsulDiscovery, error) {
consulConfig := consul.DefaultConfig()
if len(config.Address) > 0 {
consulConfig.Address = config.Address[0]
}
if config.Timeout > 0 {
consulConfig.HttpClient.Timeout = config.Timeout
}
client, err := consul.NewClient(consulConfig)
if err != nil {
return nil, fmt.Errorf("创建Consul客户端失败: %s", err.Error())
}
return &ConsulDiscovery{
client: client,
config: config,
}, nil
}
// 获取服务实例
func (d *ConsulDiscovery) GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error) {
services, _, err := d.client.Health().Service(serviceName, "", true, nil)
if err != nil {
return nil, fmt.Errorf("查询Consul服务失败: %s", err.Error())
}
instances := make([]*ServiceInstance, 0, len(services))
for _, service := range services {
instance := &ServiceInstance{
ID: service.Service.ID,
Name: service.Service.Service,
Version: d.getServiceVersion(service.Service.Tags),
Address: service.Service.Address,
Port: service.Service.Port,
Tags: service.Service.Tags,
Metadata: service.Service.Meta,
Weight: d.getServiceWeight(service.Service.Meta),
Healthy: isServiceHealthy(service),
Enable: d.isServiceEnabled(service.Service.Meta),
}
instances = append(instances, instance)
}
return instances, nil
}
// 监听服务变更
func (d *ConsulDiscovery) Watch(ctx context.Context, serviceName string) (Watcher, error) {
return NewConsulWatcher(d.client, serviceName), nil
}
// 获取服务列表
func (d *ConsulDiscovery) ListServices(ctx context.Context) ([]string, error) {
services, _, err := d.client.Catalog().Services(nil)
if err != nil {
return nil, fmt.Errorf("获取Consul服务列表失败: %s", err.Error())
}
serviceNames := make([]string, 0, len(services))
for serviceName := range services {
serviceNames = append(serviceNames, serviceName)
}
return serviceNames, nil
}
// 获取服务版本
func (d *ConsulDiscovery) getServiceVersion(tags []string) string {
if len(tags) > 0 {
for _, tag := range tags {
if !strings.HasPrefix(tag, "meta-") {
return tag
}
}
}
return "latest"
}
// 获取服务权重
func (d *ConsulDiscovery) getServiceWeight(metadata map[string]string) int {
if weightStr, exists := metadata["weight"]; exists {
if weight, err := strconv.Atoi(weightStr); err == nil {
return weight
}
}
return 1 // 默认权重
}
// 检查服务是否健康
func isServiceHealthy(service *consul.ServiceEntry) bool {
for _, check := range service.Checks {
if check.ServiceID == service.Service.ID {
return check.Status == "passing"
}
}
return false
}
// 检查服务是否启用
func (d *ConsulDiscovery) isServiceEnabled(metadata map[string]string) bool {
if enabled, exists := metadata["enabled"]; exists {
return strings.ToLower(enabled) == "true"
}
return true // 默认启用
}
// Consul监听器实现
type ConsulWatcher struct {
client *consul.Client
serviceName string
lastIndex uint64
}
// 创建Consul监听器
func NewConsulWatcher(client *consul.Client, serviceName string) *ConsulWatcher {
return &ConsulWatcher{
client: client,
serviceName: serviceName,
lastIndex: 0,
}
}
// 下一个变更事件
func (w *ConsulWatcher) Next() ([]*ServiceInstance, error) {
for {
queryOptions := &consul.QueryOptions{
WaitIndex: w.lastIndex,
WaitTime: 30 * time.Second,
}
services, meta, err := w.client.Health().Service(w.serviceName, "", true, queryOptions)
if err != nil {
return nil, fmt.Errorf("查询服务失败: %s", err.Error())
}
// 检查是否有更新
if meta.LastIndex > w.lastIndex {
w.lastIndex = meta.LastIndex
return w.convertServices(services), nil
}
}
}
// 停止监听
func (w *ConsulWatcher) Stop() error {
return nil // Consul监听器无需显式停止
}
// 转换服务列表
func (w *ConsulWatcher) convertServices(consulServices []*consul.ServiceEntry) []*ServiceInstance {
instances := make([]*ServiceInstance, 0, len(consulServices))
for _, service := range consulServices {
instance := &ServiceInstance{
ID: service.Service.ID,
Name: service.Service.Service,
Address: service.Service.Address,
Port: service.Service.Port,
Tags: service.Service.Tags,
Metadata: service.Service.Meta,
Healthy: isServiceHealthy(service),
Enable: true,
}
if len(service.Service.Tags) > 0 {
instance.Version = service.Service.Tags[0]
}
instances = append(instances, instance)
}
return instances
}
---
02.服务发现策略
a.本地缓存策略
a.内存缓存
在内存中缓存服务实例信息。
b.缓存刷新
定期刷新缓存以保持数据新鲜度。
c.缓存失效
当服务变更时及时失效缓存。
b.故障转移策略
a.实例故障转移
当实例故障时自动切换到健康实例。
b.区域故障转移
当整个区域故障时切换到其他区域。
c.多活切换
支持多活架构下的智能切换。
c.负载均衡策略
a.轮询策略
依次轮询所有可用实例。
b.随机策略
随机选择可用实例。
c.权重策略
根据权重分配请求。
d.健康检查策略
a.主动检查
定期主动检查实例健康状态。
b.被动检查
根据请求响应判断实例健康状态。
c.混合检查
结合主动和被动检查。
d.服务发现策略示例
---
// 服务发现策略示例
package strategy
import (
"context"
"math/rand"
"sort"
"sync"
"time"
)
// 服务发现策略接口
type DiscoveryStrategy interface {
// 选择服务实例
Select(instances []*ServiceInstance) *ServiceInstance
// 更新实例状态
Update(instance *ServiceInstance, err error)
// 重置策略状态
Reset()
}
// 轮询策略
type RoundRobinStrategy struct {
currentIndex int
mutex sync.Mutex
}
// 创建轮询策略
func NewRoundRobinStrategy() *RoundRobinStrategy {
return &RoundRobinStrategy{
currentIndex: 0,
}
}
// 选择实例
func (s *RoundRobinStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
if len(instances) == 0 {
return nil
}
instance := instances[s.currentIndex]
s.currentIndex = (s.currentIndex + 1) % len(instances)
return instance
}
// 更新实例状态
func (s *RoundRobinStrategy) Update(instance *ServiceInstance, err error) {
// 轮询策略不需要更新状态
}
// 重置策略
func (s *RoundRobinStrategy) Reset() {
s.mutex.Lock()
defer s.mutex.Unlock()
s.currentIndex = 0
}
// 随机策略
type RandomStrategy struct {
rand *rand.Rand
mutex sync.Mutex
}
// 创建随机策略
func NewRandomStrategy() *RandomStrategy {
return &RandomStrategy{
rand: rand.New(rand.NewSource(time.Now().UnixNano())),
}
}
// 选择实例
func (s *RandomStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
if len(instances) == 0 {
return nil
}
index := s.rand.Intn(len(instances))
return instances[index]
}
// 更新实例状态
func (s *RandomStrategy) Update(instance *ServiceInstance, err error) {
// 随机策略不需要更新状态
}
// 重置策略
func (s *RandomStrategy) Reset() {
// 随机策略无需重置
}
// 权重策略
type WeightedStrategy struct {
rand *rand.Rand
mutex sync.Mutex
}
// 创建权重策略
func NewWeightedStrategy() *WeightedStrategy {
return &WeightedStrategy{
rand: rand.New(rand.NewSource(time.Now().UnixNano())),
}
}
// 选择实例
func (s *WeightedStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 计算总权重
totalWeight := 0
for _, instance := range instances {
totalWeight += instance.Weight
}
if totalWeight <= 0 {
// 如果没有权重，使用随机选择
index := s.rand.Intn(len(instances))
return instances[index]
}
// 根据权重随机选择
randomValue := s.rand.Intn(totalWeight)
currentWeight := 0
for _, instance := range instances {
currentWeight += instance.Weight
if randomValue < currentWeight {
return instance
}
}
return instances[0]
}
// 更新实例状态
func (s *WeightedStrategy) Update(instance *ServiceInstance, err error) {
// 可以根据调用结果动态调整权重
}
// 重置策略
func (s *WeightedStrategy) Reset() {
// 权重策略无需重置
}
// 最少连接策略
type LeastConnectionsStrategy struct {
connections map[string]int
mutex sync.Mutex
}
// 创建最少连接策略
func NewLeastConnectionsStrategy() *LeastConnectionsStrategy {
return &LeastConnectionsStrategy{
connections: make(map[string]int),
}
}
// 选择实例
func (s *LeastConnectionsStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
if len(instances) == 0 {
return nil
}
var selectedInstance *ServiceInstance
minConnections := int(^uint(0) >> 1) // 最大int值
for _, instance := range instances {
connections := s.connections[instance.ID]
if connections < minConnections {
minConnections = connections
selectedInstance = instance
}
}
// 增加选中实例的连接数
if selectedInstance != nil {
s.connections[selectedInstance.ID]++
}
return selectedInstance
}
// 更新实例状态
func (s *LeastConnectionsStrategy) Update(instance *ServiceInstance, err error) {
s.mutex.Lock()
defer s.mutex.Unlock()
// 减少连接数
if count, exists := s.connections[instance.ID]; exists && count > 0 {
s.connections[instance.ID] = count - 1
}
}
// 重置策略
func (s *LeastConnectionsStrategy) Reset() {
s.mutex.Lock()
defer s.mutex.Unlock()
s.connections = make(map[string]int)
}
// 响应时间策略
type ResponseTimeStrategy struct {
responseTimes map[string]time.Duration
mutex sync.Mutex
}
// 创建响应时间策略
func NewResponseTimeStrategy() *ResponseTimeStrategy {
return &ResponseTimeStrategy{
responseTimes: make(map[string]time.Duration),
}
}
// 选择实例
func (s *ResponseTimeStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
if len(instances) == 0 {
return nil
}
// 排序实例，响应时间短的在前
sortedInstances := make([]*ServiceInstance, len(instances))
copy(sortedInstances, instances)
sort.Slice(sortedInstances, func(i, j int) bool {
timeI := s.responseTimes[sortedInstances[i].ID]
timeJ := s.responseTimes[sortedInstances[j].ID]
return timeI < timeJ
})
// 优先选择响应时间短的实例
for _, instance := range sortedInstances {
if _, exists := s.responseTimes[instance.ID]; !exists {
// 如果没有响应时间记录，优先选择
return instance
}
}
return sortedInstances[0]
}
// 更新实例状态
func (s *ResponseTimeStrategy) Update(instance *ServiceInstance, err error) {
// 这里需要在实际调用后更新响应时间
// 简化实现，实际应该在调用前后记录时间
}
// 记录响应时间
func (s *ResponseTimeStrategy) RecordResponseTime(instanceID string, responseTime time.Duration) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.responseTimes[instanceID] = responseTime
}
// 重置策略
func (s *ResponseTimeStrategy) Reset() {
s.mutex.Lock()
defer s.mutex.Unlock()
s.responseTimes = make(map[string]time.Duration)
}
// 故障检测策略
type CircuitBreakerStrategy struct {
primary DiscoveryStrategy
secondary DiscoveryStrategy
failures map[string]int
thresholds map[string]int
mutex sync.Mutex
}
// 创建故障检测策略
func NewCircuitBreakerStrategy(primary, secondary DiscoveryStrategy) *CircuitBreakerStrategy {
return &CircuitBreakerStrategy{
primary: primary,
secondary: secondary,
failures: make(map[string]int),
thresholds: make(map[string]int),
}
}
// 设置实例阈值
func (s *CircuitBreakerStrategy) SetThreshold(instanceID string, threshold int) {
s.mutex.Lock()
defer s.mutex.Unlock()
s.thresholds[instanceID] = threshold
}
// 选择实例
func (s *CircuitBreakerStrategy) Select(instances []*ServiceInstance) *ServiceInstance {
s.mutex.Lock()
defer s.mutex.Unlock()
// 过滤健康实例
healthyInstances := make([]*ServiceInstance, 0)
for _, instance := range instances {
failures := s.failures[instance.ID]
threshold := s.thresholds[instance.ID]
if threshold == 0 {
threshold = 3 // 默认阈值
}
if failures < threshold {
healthyInstances = append(healthyInstances, instance)
}
}
// 如果有健康实例，使用主策略
if len(healthyInstances) > 0 {
return s.primary.Select(healthyInstances)
}
// 否则使用备用策略
return s.secondary.Select(instances)
}
// 更新实例状态
func (s *CircuitBreakerStrategy) Update(instance *ServiceInstance, err error) {
s.mutex.Lock()
defer s.mutex.Unlock()
if err != nil {
s.failures[instance.ID]++
} else {
// 成功调用，重置失败计数
delete(s.failures, instance.ID)
}
}
// 重置策略
func (s *CircuitBreakerStrategy) Reset() {
s.mutex.Lock()
defer s.mutex.Unlock()
s.failures = make(map[string]int)
s.primary.Reset()
if s.secondary != nil {
s.secondary.Reset()
}
}
// 策略工厂
type StrategyFactory struct{}
// 创建策略
func (f *StrategyFactory) CreateStrategy(strategyType string) DiscoveryStrategy {
switch strategyType {
case "round_robin":
return NewRoundRobinStrategy()
case "random":
return NewRandomStrategy()
case "weighted":
return NewWeightedStrategy()
case "least_connections":
return NewLeastConnectionsStrategy()
case "response_time":
return NewResponseTimeStrategy()
default:
return NewRoundRobinStrategy() // 默认策略
}
}
// 创建组合策略
func (f *StrategyFactory) CreateCircuitBreakerStrategy(primaryType, secondaryType string) DiscoveryStrategy {
primary := f.CreateStrategy(primaryType)
secondary := f.CreateStrategy(secondaryType)
return NewCircuitBreakerStrategy(primary, secondary)
}
---
3 服务构建与生命周期
3.1 汇总：服务构建流程
01.Kratos应用构建概览
a.应用构建阶段
a.初始化阶段
配置加载、日志设置、依赖初始化等准备工作。
b.组件注册阶段
注册服务器、中间件、服务发现等核心组件。
c.服务启动阶段
启动HTTP/gRPC服务器，开始接受请求。
d.运行监控阶段
健康检查、指标收集、日志记录等运行时监控。
e.优雅关闭阶段
停止接受新请求，完成现有请求，清理资源。
b.构建流程特点
a.组件化设计
各功能组件独立可插拔，支持按需组装。
b.配置驱动
通过配置文件控制应用行为，支持多环境部署。
c.生命周期管理
完整的生命周期回调机制，支持资源管理。
d.错误处理
统一的错误处理和恢复机制，保证系统稳定性。
c.服务构建示例
---
// Kratos应用构建完整示例
package main
import (
"context"
"flag"
"os"
"os/signal"
"syscall"
"time"
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/registry"
)
// 应用配置结构
type AppConfig struct {
Server ServerConfig `json:"server"`
Data DataConfig `json:"data"`
Log LogConfig `json:"log"`
Auth AuthConfig `json:"auth"`
Registry RegistryConfig `json:"registry"`
}
type ServerConfig struct {
HTTP HTTPConfig `json:"http"`
GRPC GRPCConfig `json:"grpc"`
}
type HTTPConfig struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
}
type GRPCConfig struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
}
// 应用构建器
type AppBuilder struct {
config *AppConfig
logger log.Logger
app *kratos.App
}
func NewAppBuilder() *AppBuilder {
return &AppBuilder{}
}
// 步骤1: 加载配置
func (b *AppBuilder) LoadConfig(configPath string) *AppBuilder {
c := config.New(
config.WithSource(
file.NewSource(configPath),
),
)
if err := c.Load(); err != nil {
panic(fmt.Errorf("加载配置失败: %w", err))
}
var cfg AppConfig
if err := c.Scan(&cfg); err != nil {
panic(fmt.Errorf("解析配置失败: %w", err))
}
b.config = &cfg
return b
}
// 步骤2: 初始化日志
func (b *AppBuilder) InitLogger() *AppBuilder {
b.logger = log.NewStdLogger(os.Stdout,
log.WithLevel(getLogLevel(b.config.Log.Level)),
log.WithContext(log.WithCaller()),
log.WithMessageKey("msg"),
)
b.logger = log.With(b.logger,
"service.id", b.getID(),
"service.name", b.getName(),
"service.version", b.getVersion(),
"trace.id", log.TraceID(),
"span.id", log.SpanID(),
)
return b
}
// 步骤3: 创建应用实例
func (b *AppBuilder) CreateApp() *AppBuilder {
// 创建HTTP服务器
httpSrv := b.createHTTPServer()
// 创建gRPC服务器
grpcSrv := b.createGRPCServer()
// 创建注册中心实例
reg := b.createRegistry()
// 创建Kratos应用
b.app = kratos.New(
kratos.ID(b.getID()),
kratos.Name(b.getName()),
kratos.Version(b.getVersion()),
kratos.Metadata(b.getMetadata()),
kratos.Logger(b.logger),
kratos.Server(
httpSrv,
grpcSrv,
),
kratos.Registrar(reg),
// 生命周期回调
kratos.BeforeStart(b.beforeStart()),
kratos.AfterStart(b.afterStart()),
kratos.BeforeStop(b.beforeStop()),
kratos.AfterStop(b.afterStop()),
)
return b
}
// 创建HTTP服务器
func (b *AppBuilder) createHTTPServer() *http.Server {
return http.NewServer(
http.Address(b.config.Server.HTTP.Addr),
http.Timeout(b.config.Server.HTTP.Timeout),
http.Middleware(
recovery.Recovery(),
logging.Server(b.logger),
metrics.Server(),
tracing.Server(),
b.authMiddleware(),
b.corsMiddleware(),
),
)
}
// 创建gRPC服务器
func (b *AppBuilder) createGRPCServer() *grpc.Server {
return grpc.NewServer(
grpc.Address(b.config.Server.GRPC.Addr),
grpc.Timeout(b.config.Server.GRPC.Timeout),
grpc.Middleware(
recovery.Recovery(),
logging.Server(b.logger),
metrics.Server(),
tracing.Server(),
b.authGRPCMiddleware(),
),
)
}
// 创建注册中心
func (b *AppBuilder) createRegistry() registry.Registrar {
// 根据配置创建不同的注册中心
switch b.config.Registry.Type {
case "consul":
return b.createConsulRegistry()
case "etcd":
return b.createEtcdRegistry()
case "nacos":
return b.createNacosRegistry()
default:
return nil
}
}
// 应用启动前回调
func (b *AppBuilder) beforeStart() func(ctx context.Context) error {
return func(ctx context.Context) error {
b.logger.Info("应用启动前准备...")
// 初始化数据库连接
if err := b.initDatabase(); err != nil {
return fmt.Errorf("初始化数据库失败: %w", err)
}
// 缓存预热
if err := b.warmupCache(); err != nil {
b.logger.Warnf("缓存预热失败: %v", err)
}
// 注册服务
if err := b.registerServices(); err != nil {
return fmt.Errorf("注册服务失败: %w", err)
}
b.logger.Info("应用启动前准备完成")
return nil
}
}
// 应用启动后回调
func (b *AppBuilder) afterStart() func(ctx context.Context) error {
return func(ctx context.Context) error {
b.logger.Info("应用启动完成...")
// 启动后台任务
b.startBackgroundTasks(ctx)
// 启动健康检查
b.startHealthCheck(ctx)
// 启动指标收集
b.startMetricsCollection(ctx)
b.logger.Infof("服务已启动，HTTP: %s, gRPC: %s",
b.config.Server.HTTP.Addr,
b.config.Server.GRPC.Addr)
return nil
}
}
// 应用停止前回调
func (b *AppBuilder) beforeStop() func(ctx context.Context) error {
return func(ctx context.Context) error {
b.logger.Info("应用停止前清理...")
// 停止接受新请求
b.stopAcceptingRequests()
// 等待现有请求完成
b.waitForRequestsCompletion(ctx)
// 注销服务
if err := b.deregisterServices(); err != nil {
b.logger.Warnf("注销服务失败: %v", err)
}
b.logger.Info("应用停止前清理完成")
return nil
}
}
// 应用停止后回调
func (b *AppBuilder) afterStop() func(ctx context.Context) error {
return func(ctx context.Context) error {
b.logger.Info("应用停止完成...")
// 清理数据库连接
b.cleanupDatabase()
// 清理缓存
b.cleanupCache()
// 清理其他资源
b.cleanupResources()
b.logger.Info("应用清理完成")
return nil
}
}
// 获取应用实例
func (b *AppBuilder) Build() *kratos.App {
if b.app == nil {
panic("请先调用 CreateApp() 方法")
}
return b.app
}
// 运行应用
func (b *AppBuilder) Run() error {
if b.app == nil {
panic("请先调用 Build() 方法")
}
// 设置信号处理
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// 优雅关闭处理
go func() {
c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGINT, syscall.SIGTERM)
<-c
b.logger.Info("收到停止信号，开始优雅关闭...")
cancel()
}()
// 启动应用
if err := b.app.Run(ctx); err != nil {
return fmt.Errorf("应用运行失败: %w", err)
}
return nil
}
// 辅助方法实现
func (b *AppBuilder) getID() string {
return os.Getenv("SERVICE_ID")
}
func (b *AppBuilder) getName() string {
name := os.Getenv("SERVICE_NAME")
if name == "" {
name = "kratos-service"
}
return name
}
func (b *AppBuilder) getVersion() string {
version := os.Getenv("SERVICE_VERSION")
if version == "" {
version = "1.0.0"
}
return version
}
func (b *AppBuilder) getMetadata() map[string]string {
return map[string]string{
"env": os.Getenv("ENVIRONMENT"),
"region": os.Getenv("REGION"),
"zone": os.Getenv("ZONE"),
}
}
func getLogLevel(level string) log.Level {
switch level {
case "debug":
return log.LevelDebug
case "info":
return log.LevelInfo
case "warn":
return log.LevelWarn
case "error":
return log.LevelError
default:
return log.LevelInfo
}
}
// 主函数
func main() {
var configPath string
flag.StringVar(&configPath, "conf", "configs/config.yaml", "配置文件路径")
flag.Parse()
// 构建应用
app := NewAppBuilder().
LoadConfig(configPath).
InitLogger().
CreateApp().
Build()
// 运行应用
if err := app.Run(); err != nil {
log.Fatalf("应用运行失败: %v", err)
}
}
---
02.应用构建最佳实践
a.配置管理
a.分层配置
支持默认配置、环境配置、命令行参数的分层覆盖。
b.敏感信息
使用环境变量或密钥管理系统处理敏感配置。
c.配置验证
启动时验证配置的完整性和有效性。
d.配置热更
支持运行时配置更新，无需重启服务。
b.依赖管理
a.接口依赖
基于接口的依赖注入，降低组件间耦合。
b.生命周期管理
明确定义组件的创建、初始化、销毁顺序。
c.循环依赖
避免循环依赖，使用事件或观察者模式解耦。
d.依赖注入最佳实践示例
---
// 依赖注入最佳实践示例
package di
import (
"context"
"fmt"
"reflect"
"sync"
)
// 容器接口
type Container interface {
Register(name string, factory Factory) error
RegisterSingleton(name string, factory Factory) error
Resolve(name string) (interface{}, error)
ResolveAs(name string, target interface{}) error
ResolveAll(target interface{}) error
}
// 工厂函数类型
type Factory func(c Container) (interface{}, error)
// 依赖注入容器实现
type DIContainer struct {
services map[string]*serviceDefinition
singletons map[string]interface{}
mutex sync.RWMutex
constructing map[string]bool // 防止循环依赖
}
type serviceDefinition struct {
factory Factory
singleton bool
instance interface{}
constructed bool
}
func NewContainer() Container {
return &DIContainer{
services: make(map[string]*serviceDefinition),
singletons: make(map[string]interface{}),
constructing: make(map[string]bool),
}
}
// 注册服务
func (c *DIContainer) Register(name string, factory Factory) error {
c.mutex.Lock()
defer c.mutex.Unlock()
if _, exists := c.services[name]; exists {
return fmt.Errorf("服务 %s 已注册", name)
}
c.services[name] = &serviceDefinition{
factory: factory,
singleton: false,
}
return nil
}
// 注册单例服务
func (c *DIContainer) RegisterSingleton(name string, factory Factory) error {
c.mutex.Lock()
defer c.mutex.Unlock()
if _, exists := c.services[name]; exists {
return fmt.Errorf("服务 %s 已注册", name)
}
c.services[name] = &serviceDefinition{
factory: factory,
singleton: true,
}
return nil
}
// 解析服务
func (c *DIContainer) Resolve(name string) (interface{}, error) {
c.mutex.RLock()
def, exists := c.services[name]
c.mutex.RUnlock()
if !exists {
return nil, fmt.Errorf("服务 %s 未注册", name)
}
// 检查循环依赖
if c.isConstructing(name) {
return nil, fmt.Errorf("检测到循环依赖: %s", name)
}
// 单例模式
if def.singleton {
return c.resolveSingleton(name, def)
}
// 每次创建新实例
return c.createInstance(name, def)
}
// 解析单例服务
func (c *DIContainer) resolveSingleton(name string, def *serviceDefinition) (interface{}, error) {
if def.instance != nil {
return def.instance, nil
}
c.mutex.Lock()
defer c.mutex.Unlock()
// 双重检查
if def.instance != nil {
return def.instance, nil
}
instance, err := c.createInstance(name, def)
if err != nil {
return nil, err
}
def.instance = instance
return instance, nil
}
// 创建实例
func (c *DIContainer) createInstance(name string, def *serviceDefinition) (interface{}, error) {
c.markConstructing(name, true)
defer c.markConstructing(name, false)
return def.factory(c)
}
// 解析到指定类型
func (c *DIContainer) ResolveAs(name string, target interface{}) error {
instance, err := c.Resolve(name)
if err != nil {
return err
}
targetValue := reflect.ValueOf(target)
if targetValue.Kind() != reflect.Ptr {
return fmt.Errorf("target 必须是指针类型")
}
instanceValue := reflect.ValueOf(instance)
targetValue.Elem().Set(instanceValue)
return nil
}
// 批量解析
func (c *DIContainer) ResolveAll(target interface{}) error {
targetValue := reflect.ValueOf(target)
if targetValue.Kind() != reflect.Ptr || targetValue.Elem().Kind() != reflect.Struct {
return fmt.Errorf("target 必须是指向结构体的指针")
}
structValue := targetValue.Elem()
structType := structValue.Type()
for i := 0; i < structValue.NumField(); i++ {
field := structValue.Field(i)
fieldType := structType.Field(i)
// 获取注入标签
injectTag := fieldType.Tag.Get("inject")
if injectTag == "" {
continue
}
instance, err := c.Resolve(injectTag)
if err != nil {
return fmt.Errorf("解析字段 %s 失败: %w", fieldType.Name, err)
}
if field.CanSet() {
field.Set(reflect.ValueOf(instance))
}
}
return nil
}
// 循环依赖检测
func (c *DIContainer) isConstructing(name string) bool {
c.mutex.RLock()
defer c.mutex.RUnlock()
return c.constructing[name]
}
func (c *DIContainer) markConstructing(name string, constructing bool) {
c.mutex.Lock()
defer c.mutex.Unlock()
c.constructing[name] = constructing
}
// 服务注册和解析示例
func ExampleDIUsage() {
container := NewContainer()
// 注册配置服务
container.RegisterSingleton("config", func(c Container) (interface{}, error) {
return &ConfigService{
DatabaseURL: "mysql://localhost:3306/mydb",
RedisURL: "redis://localhost:6379",
}, nil
})
// 注册数据库服务
container.RegisterSingleton("database", func(c Container) (interface{}, error) {
config, err := c.Resolve("config")
if err != nil {
return nil, err
}
configService := config.(*ConfigService)
return &DatabaseService{
URL: configService.DatabaseURL,
}, nil
})
// 注册缓存服务
container.Register("cache", func(c Container) (interface{}, error) {
config, err := c.Resolve("config")
if err != nil {
return nil, err
}
configService := config.(*ConfigService)
return &CacheService{
URL: configService.RedisURL,
}, nil
})
// 注册用户服务
container.Register("userService", func(c Container) (interface{}, error) {
db, err := c.Resolve("database")
if err != nil {
return nil, err
}
cache, err := c.Resolve("cache")
if err != nil {
return nil, err
}
return &UserService{
Database: db.(*DatabaseService),
Cache: cache.(*CacheService),
}, nil
})
// 解析用户服务
userService, err := container.Resolve("userService")
if err != nil {
panic(err)
}
userSvc := userService.(*UserService)
fmt.Printf("用户服务创建成功: %T\n", userSvc)
// 结构体注入示例
type App struct {
UserService UserService `inject:"userService"`
Database DatabaseService `inject:"database"`
Cache CacheService `inject:"cache"`
}
var app App
if err := container.ResolveAll(&app); err != nil {
panic(err)
}
fmt.Printf("应用结构体注入成功: %+v\n", app)
}
// 服务接口定义
type UserService interface {
GetUser(id string) (*User, error)
CreateUser(user *User) error
}
type DatabaseService interface {
Query(query string, args ...interface{}) (*Result, error)
Execute(query string, args ...interface{}) error
}
type CacheService interface {
Get(key string) (interface{}, error)
Set(key string, value interface{}, expiration time.Duration) error
}
// 具体服务实现
type ConfigService struct {
DatabaseURL string
RedisURL string
}
type CacheServiceImpl struct {
URL string
}
func (c *CacheServiceImpl) Get(key string) (interface{}, error) {
// 缓存获取逻辑
return nil, nil
}
func (c *CacheServiceImpl) Set(key string, value interface{}, expiration time.Duration) error {
// 缓存设置逻辑
return nil
}
type DatabaseServiceImpl struct {
URL string
}
func (d *DatabaseServiceImpl) Query(query string, args ...interface{}) (*Result, error) {
// 数据库查询逻辑
return nil, nil
}
func (d *DatabaseServiceImpl) Execute(query string, args ...interface{}) error {
// 数据库执行逻辑
return nil
}
type UserServiceImpl struct {
Database DatabaseService
Cache CacheService
}
func (u *UserServiceImpl) GetUser(id string) (*User, error) {
// 用户获取逻辑
return nil, nil
}
func (u *UserServiceImpl) CreateUser(user *User) error {
// 用户创建逻辑
return nil
}
type User struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
type Result struct {
RowsAffected int64
LastInsertID int64
}
---
3.2 Kratos 应用的构成
01.应用架构概述
a.分层架构设计
Kratos采用分层架构模式，将应用划分为多个独立且相互协作的层次，确保代码的可维护性和扩展性。每一层都有明确的职责和边界，通过依赖倒置原则实现松耦合设计。
b.核心组件层次
Server层负责网络通信和协议处理，Service层处理业务逻辑，Repository层负责数据访问，各层通过接口进行交互，支持单元测试和模块替换。
02.Server接口层详解
a.Server层职责
Server层作为应用的网络入口，负责处理HTTP/gRPC请求、参数解析、响应生成等网络通信相关的功能，同时集成中间件链进行横切关注点处理。
b.HTTP服务器组件
a.功能说明
HTTP服务器基于标准库net/http构建，支持RESTful API设计，内置路由匹配、参数绑定、响应序列化等功能，通过中间件机制扩展业务能力。
b.代码示例
---
// HTTP服务器创建和配置示例
package server
import (
"context"
"encoding/json"
"fmt"
"net/http"
"time"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
)
// HTTP服务器配置
type HTTPServerConfig struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
ReadTimeout time.Duration `json:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout"`
IdleTimeout time.Duration `json:"idle_timeout"`
MaxHeaderBytes int `json:"max_header_bytes"`
}
// HTTP服务器构建器
type HTTPServerBuilder struct {
config *HTTPServerConfig
logger log.Logger
middleware []http.ServerMiddleware
routers []http.Router
}
func NewHTTPServerBuilder(config *HTTPServerConfig) *HTTPServerBuilder {
return &HTTPServerBuilder{
config: config,
middleware: make([]http.ServerMiddleware, 0),
routers: make([]http.Router, 0),
}
}
// 添加中间件
func (b *HTTPServerBuilder) WithMiddleware(middleware ...http.ServerMiddleware) *HTTPServerBuilder {
b.middleware = append(b.middleware, middleware...)
return b
}
// 添加路由
func (b *HTTPServerBuilder) WithRouter(routers ...http.Router) *HTTPServerBuilder {
b.routers = append(b.routers, routers...)
return b
}
// 构建HTTP服务器
func (b *HTTPServerBuilder) Build() *http.Server {
// 设置默认中间件
defaultMiddleware := []http.ServerMiddleware{
recovery.Recovery(), // 恢复中间件
logging.Server(b.logger), // 日志中间件
metrics.Server(), // 指标收集中间件
tracing.Server(), // 链路追踪中间件
}
// 合并中间件
allMiddleware := append(defaultMiddleware, b.middleware...)
// 创建HTTP服务器
srv := http.NewServer(
http.Address(b.config.Addr),
http.Timeout(b.config.Timeout),
http.Middleware(allMiddleware...),
http.ResponseEncoder(b.responseEncoder),
http.RequestDecoder(b.requestDecoder),
http.ErrorEncoder(b.errorEncoder),
http.Router(b.routers...),
)
return srv
}
// 响应编码器
func (b *HTTPServerBuilder) responseEncoder(w http.ResponseWriter, r *http.Request, v interface{}) error {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
// 设置跨域头
if origin := r.Header.Get("Origin"); origin != "" {
w.Header().Set("Access-Control-Allow-Origin", origin)
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
w.Header().Set("Access-Control-Max-Age", "86400")
}
// 处理OPTIONS请求
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return nil
}
// 编码响应
if err := json.NewEncoder(w).Encode(v); err != nil {
return fmt.Errorf("编码响应失败: %w", err)
}
return nil
}
// 请求解码器
func (b *HTTPServerBuilder) requestDecoder(r *http.Request, v interface{}) error {
if r.Body == nil {
return nil
}
defer r.Body.Close()
if err := json.NewDecoder(r.Body).Decode(v); err != nil {
return fmt.Errorf("解码请求失败: %w", err)
}
return nil
}
// 错误编码器
func (b *HTTPServerBuilder) errorEncoder(w http.ResponseWriter, r *http.Request, err error) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
// 根据错误类型设置HTTP状态码
var statusCode int
switch e := err.(type) {
case *ValidationError:
statusCode = http.StatusBadRequest
case *NotFoundError:
statusCode = http.StatusNotFound
case *UnauthorizedError:
statusCode = http.StatusUnauthorized
case *ForbiddenError:
statusCode = http.StatusForbidden
case *ConflictError:
statusCode = http.StatusConflict
default:
statusCode = http.StatusInternalServerError
}
w.WriteHeader(statusCode)
// 构建错误响应
errorResponse := map[string]interface{}{
"error": map[string]interface{}{
"code": statusCode,
"message": err.Error(),
"details": b.getErrorDetails(err),
},
"timestamp": time.Now().Unix(),
"path": r.URL.Path,
"method": r.Method,
}
json.NewEncoder(w).Encode(errorResponse)
}
// HTTP服务器使用示例
func ExampleHTTPServerUsage() {
config := &HTTPServerConfig{
Addr: ":8080",
Timeout: 30 * time.Second,
ReadTimeout: 15 * time.Second,
WriteTimeout: 15 * time.Second,
IdleTimeout: 60 * time.Second,
MaxHeaderBytes: 1 << 20, // 1MB
}
// 创建HTTP服务器构建器
builder := NewHTTPServerBuilder(config)
// 添加自定义中间件
builder.WithMiddleware(
authMiddleware(),
rateLimitMiddleware(),
corsMiddleware(),
)
// 构建服务器
httpServer := builder.Build()
fmt.Printf("HTTP服务器创建成功，监听地址: %s\n", config.Addr)
_ = httpServer
}
---
c.gRPC服务器组件
a.功能说明
gRPC服务器基于gRPC框架构建，支持高性能的RPC通信，内置流式处理、负载均衡、服务发现等功能，通过Protocol Buffers定义服务接口。
b.代码示例
---
// gRPC服务器创建和配置示例
package grpc
import (
"context"
"fmt"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
"google.golang.org/grpc/keepalive"
"google.golang.org/grpc/reflection"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
)
// gRPC服务器配置
type GRPCServerConfig struct {
Addr string `json:"addr"`
Timeout time.Duration `json:"timeout"`
MaxRecvMsgSize int `json:"max_recv_msg_size"`
MaxSendMsgSize int `json:"max_send_msg_size"`
MaxConcurrentStreams int `json:"max_concurrent_streams"`
Keepalive KeepaliveConfig `json:"keepalive"`
TLS TLSConfig `json:"tls"`
}
type KeepaliveConfig struct {
Time time.Duration `json:"time"`
Timeout time.Duration `json:"timeout"`
PermitWithoutStream bool `json:"permit_without_stream"`
MinTime time.Duration `json:"min_time"`
}
type TLSConfig struct {
Enabled bool `json:"enabled"`
CertFile string `json:"cert_file"`
KeyFile string `json:"key_file"`
CAFile string `json:"ca_file"`
}
// gRPC服务器构建器
type GRPCServerBuilder struct {
config *GRPCServerConfig
logger log.Logger
middleware []grpc.ServerMiddleware
services []grpc.ServiceRegistrar
interceptors []grpc.UnaryServerInterceptor
streamInterceptors []grpc.StreamServerInterceptor
}
func NewGRPCServerBuilder(config *GRPCServerConfig) *GRPCServerBuilder {
return &GRPCServerBuilder{
config: config,
middleware: make([]grpc.ServerMiddleware, 0),
services: make([]grpc.ServiceRegistrar, 0),
interceptors: make([]grpc.UnaryServerInterceptor, 0),
streamInterceptors: make([]grpc.StreamServerInterceptor, 0),
}
}
// 构建gRPC服务器
func (b *GRPCServerBuilder) Build() *grpc.Server {
// 设置默认中间件
defaultMiddleware := []grpc.ServerMiddleware{
recovery.Recovery(), // 恢复中间件
logging.Server(b.logger), // 日志中间件
metrics.Server(), // 指标收集中间件
tracing.Server(), // 链路追踪中间件
}
// 合并中间件
allMiddleware := append(defaultMiddleware, b.middleware...)
// 创建gRPC服务器选项
var opts []grpc.ServerOption
// 设置中间件
opts = append(opts, grpc.Middleware(allMiddleware...))
// 设置拦截器
if len(b.interceptors) > 0 {
opts = append(opts, grpc.UnaryInterceptor(b.chainUnaryInterceptors(b.interceptors...)))
}
if len(b.streamInterceptors) > 0 {
opts = append(opts, grpc.StreamInterceptor(b.chainStreamInterceptors(b.streamInterceptors...)))
}
// 设置传输参数
opts = append(opts,
grpc.MaxRecvMsgSize(b.config.MaxRecvMsgSize),
grpc.MaxSendMsgSize(b.config.MaxSendMsgSize),
grpc.MaxConcurrentStreams(uint32(b.config.MaxConcurrentStreams)),
)
// 设置Keepalive
ka := keepalive.ServerParameters{
Time: b.config.Keepalive.Time,
Timeout: b.config.Keepalive.Timeout,
PermitWithoutStream: b.config.Keepalive.PermitWithoutStream,
MinTime: b.config.Keepalive.MinTime,
}
opts = append(opts, grpc.KeepaliveParams(ka))
// 设置TLS
if b.config.TLS.Enabled {
creds, err := b.loadTLSCredentials()
if err != nil {
panic(fmt.Sprintf("加载TLS证书失败: %v", err))
}
opts = append(opts, grpc.Creds(creds))
}
// 创建gRPC服务器
srv := grpc.NewServer(opts...)
// 启用反射（开发环境）
if os.Getenv("ENVIRONMENT") == "development" {
reflection.Register(srv)
}
return srv
}
// gRPC服务器使用示例
func ExampleGRPCServerUsage() {
config := &GRPCServerConfig{
Addr: ":9090",
Timeout: 30 * time.Second,
MaxRecvMsgSize: 4 * 1024 * 1024, // 4MB
MaxSendMsgSize: 4 * 1024 * 1024, // 4MB
MaxConcurrentStreams: 1000,
Keepalive: KeepaliveConfig{
Time: 5 * time.Minute,
Timeout: 20 * time.Second,
PermitWithoutStream: true,
MinTime: 1 * time.Minute,
},
TLS: TLSConfig{
Enabled: false,
CertFile: "",
KeyFile: "",
CAFile: "",
},
}
// 创建gRPC服务器构建器
builder := NewGRPCServerBuilder(config)
// 添加自定义拦截器
builder.WithInterceptor(
authUnaryInterceptor(),
rateLimitUnaryInterceptor(),
metricsUnaryInterceptor(),
)
// 构建服务器
grpcServer := builder.Build()
fmt.Printf("gRPC服务器创建成功，监听地址: %s\n", config.Addr)
_ = grpcServer
}
---
03.Service业务逻辑层详解
a.Service层职责
Service层负责处理业务逻辑、数据验证、事务管理等核心业务功能，通过依赖注入与Repository层交互，实现业务规则的集中管理和复用。
b.服务接口设计
a.接口定义原则
Service接口应遵循单一职责原则，每个接口专注于特定的业务领域，接口方法应保持简洁明了，参数和返回值类型要明确具体。
b.代码示例
---
// 业务服务接口定义示例
package service
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/errors"
"google.golang.org/grpc/codes"
)
// 用户服务接口
type UserService interface {
// 获取用户信息
GetUser(ctx context.Context, req *GetUserRequest) (*GetUserResponse, error)
// 创建用户
CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error)
// 更新用户信息
UpdateUser(ctx context.Context, req *UpdateUserRequest) (*UpdateUserResponse, error)
// 删除用户
DeleteUser(ctx context.Context, req *DeleteUserRequest) (*DeleteUserResponse, error)
// 获取用户列表
ListUsers(ctx context.Context, req *ListUsersRequest) (*ListUsersResponse, error)
// 用户认证
AuthenticateUser(ctx context.Context, req *AuthenticateUserRequest) (*AuthenticateUserResponse, error)
// 修改密码
ChangePassword(ctx context.Context, req *ChangePasswordRequest) (*ChangePasswordResponse, error)
}
// 订单服务接口
type OrderService interface {
// 创建订单
CreateOrder(ctx context.Context, req *CreateOrderRequest) (*CreateOrderResponse, error)
// 获取订单详情
GetOrder(ctx context.Context, req *GetOrderRequest) (*GetOrderResponse, error)
// 更新订单状态
UpdateOrderStatus(ctx context.Context, req *UpdateOrderStatusRequest) (*UpdateOrderStatusResponse, error)
// 取消订单
CancelOrder(ctx context.Context, req *CancelOrderRequest) (*CancelOrderResponse, error)
// 获取用户订单列表
GetUserOrders(ctx context.Context, req *GetUserOrdersRequest) (*GetUserOrdersResponse, error)
}
// 请求和响应结构体定义
type GetUserRequest struct {
UserID string `json:"user_id" validate:"required"`
}
type GetUserResponse struct {
User *User `json:"user"`
}
type CreateUserRequest struct {
Name string `json:"name" validate:"required,min=2,max=50"`
Email string `json:"email" validate:"required,email"`
Phone string `json:"phone" validate:"omitempty,phone"`
Age int `json:"age" validate:"omitempty,min=18,max=120"`
Address string `json:"address"`
Password string `json:"password" validate:"required,min=8,max=128"`
}
type CreateUserResponse struct {
User *User `json:"user"`
}
type User struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
Phone string `json:"phone"`
Age int `json:"age"`
Address string `json:"address"`
Password string `json:"-"` // 不返回密码
Status string `json:"status"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
---
04.Repository数据访问层详解
a.Repository层职责
Repository层负责数据持久化操作，抽象了数据存储细节，提供统一的数据访问接口，支持多种数据源和存储方式。
b.数据访问接口设计
a.接口设计原则
Repository接口应专注于数据访问逻辑，不包含业务规则，方法命名应清晰表达操作意图，支持复杂查询和事务操作。
b.代码示例
---
// 数据访问层接口定义示例
package repository
import (
"context"
"time"
"github.com/go-kratos/kratos/v2/errors"
)
// 用户仓储接口
type UserRepository interface {
// 基础CRUD操作
Create(ctx context.Context, user *User) error
GetByID(ctx context.Context, id string) (*User, error)
Update(ctx context.Context, user *User) error
Delete(ctx context.Context, id string) error
// 查询操作
GetByEmail(ctx context.Context, email string) (*User, error)
List(ctx context.Context, filter *UserFilter, pagination *Pagination) ([]*User, int64, error)
Search(ctx context.Context, query *UserSearchQuery) ([]*User, error)
// 存在性检查
ExistsByID(ctx context.Context, id string) (bool, error)
ExistsByEmail(ctx context.Context, email string) (bool, error)
ExistsByEmailExcluding(ctx context.Context, email string, excludeID string) (bool, error)
// 批量操作
BatchCreate(ctx context.Context, users []*User) error
BatchUpdate(ctx context.Context, users []*User) error
BatchDelete(ctx context.Context, ids []string) error
// 状态管理
UpdateStatus(ctx context.Context, id string, status string) error
UpdateLastLogin(ctx context.Context, id string, lastLogin time.Time) error
// 统计查询
CountByStatus(ctx context.Context, status string) (int64, error)
CountByCreatedAtRange(ctx context.Context, startTime, endTime time.Time) (int64, error)
// 缓存相关
InvalidateCache(ctx context.Context, id string) error
WarmupCache(ctx context.Context, ids []string) error
}
// 数据模型定义
type User struct {
ID string `json:"id" db:"id"`
Name string `json:"name" db:"name"`
Email string `json:"email" db:"email"`
Phone string `json:"phone" db:"phone"`
Age int `json:"age" db:"age"`
Address string `json:"address" db:"address"`
Password string `json:"-" db:"password"`
Status string `json:"status" db:"status"`
CreatedAt time.Time `json:"created_at" db:"created_at"`
UpdatedAt time.Time `json:"updated_at" db:"updated_at"`
LastLogin *time.Time `json:"last_login" db:"last_login"`
}
// 查询和过滤结构
type UserFilter struct {
Status string `json:"status"`
AgeRange *AgeRange `json:"age_range"`
CreatedAt *TimeRange `json:"created_at"`
}
type AgeRange struct {
Min int `json:"min"`
Max int `json:"max"`
}
type TimeRange struct {
Start time.Time `json:"start"`
End time.Time `json:"end"`
}
type Pagination struct {
Page int `json:"page"`
PageSize int `json:"page_size"`
SortBy string `json:"sort_by"`
SortDir string `json:"sort_dir"`
}
type UserSearchQuery struct {
Keyword string `json:"keyword"`
Fields []string `json:"fields"`
Filter *UserFilter `json:"filter"`
Limit int `json:"limit"`
}
---
05.依赖注入与配置管理
a.依赖注入容器
a.容器设计原则
依赖注入容器负责管理服务的生命周期和依赖关系，支持单例和瞬时两种生命周期模式，提供类型安全的依赖解析和循环依赖检测。
b.配置管理
支持多层级配置系统，包括默认配置、文件配置、环境变量配置等，提供配置热更新和监听机制。
c.代码示例
---
// 依赖注入和配置管理集成示例
package di
import (
"context"
"fmt"
"sync"
"time"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/config/env"
"github.com/go-kratos/kratos/v2/log"
)
// 应用容器
type ApplicationContainer struct {
container Container
config config.Config
logger log.Logger
mutex sync.RWMutex
}
// 创建应用容器
func NewApplicationContainer(configPath string, logger log.Logger) (*ApplicationContainer, error) {
// 创建配置源
sources := []config.Source{
file.NewSource(configPath),
env.NewSource("APP_"), // 环境变量前缀
}
// 创建配置实例
c := config.New(
config.WithSource(sources...),
)
// 加载配置
if err := c.Load(); err != nil {
return nil, fmt.Errorf("加载配置失败: %w", err)
}
// 创建依赖注入容器
container := NewContainer()
return &ApplicationContainer{
container: container,
config: c,
logger: logger,
}, nil
}
// 注册核心服务
func (ac *ApplicationContainer) RegisterCoreServices() error {
// 注册配置服务
if err := ac.container.RegisterSingleton("config", func(c Container) (interface{}, error) {
return &ConfigService{
config: ac.config,
logger: ac.logger,
}, nil
}); err != nil {
return fmt.Errorf("注册配置服务失败: %w", err)
}
// 注册日志服务
if err := ac.container.RegisterSingleton("logger", func(c Container) (interface{}, error) {
return ac.logger, nil
}); err != nil {
return fmt.Errorf("注册日志服务失败: %w", err)
}
// 注册数据库服务
if err := ac.container.RegisterSingleton("database", func(c Container) (interface{}, error) {
configService, err := c.Resolve("config")
if err != nil {
return nil, err
}
config := configService.(*ConfigService)
return NewDatabaseService(config.GetDatabaseConfig(), ac.logger)
}); err != nil {
return fmt.Errorf("注册数据库服务失败: %w", err)
}
// 注册缓存服务
if err := ac.container.RegisterSingleton("cache", func(c Container) (interface{}, error) {
configService, err := c.Resolve("config")
if err != nil {
return nil, err
}
config := configService.(*ConfigService)
return NewCacheService(config.GetCacheConfig(), ac.logger)
}); err != nil {
return fmt.Errorf("注册缓存服务失败: %w", err)
}
return nil
}
// 注册业务服务
func (ac *ApplicationContainer) RegisterBusinessServices() error {
// 注册用户仓储
if err := ac.container.RegisterSingleton("userRepository", func(c Container) (interface{}, error) {
db, err := c.Resolve("database")
if err != nil {
return nil, err
}
cache, err := c.Resolve("cache")
if err != nil {
return nil, err
}
return NewUserRepository(db.(*DatabaseService), cache.(*CacheService), ac.logger), nil
}); err != nil {
return fmt.Errorf("注册用户仓储失败: %w", err)
}
// 注册用户服务
if err := ac.container.Register("userService", func(c Container) (interface{}, error) {
userRepo, err := c.Resolve("userRepository")
if err != nil {
return nil, err
}
logger, err := c.Resolve("logger")
if err != nil {
return nil, err
}
return NewUserService(userRepo.(UserRepository), logger.(log.Logger)), nil
}); err != nil {
return fmt.Errorf("注册用户服务失败: %w", err)
}
return nil
}
// 解析服务
func (ac *ApplicationContainer) Resolve(name string) (interface{}, error) {
return ac.container.Resolve(name)
}
// 解析到指定类型
func (ac *ApplicationContainer) ResolveAs(name string, target interface{}) error {
return ac.container.ResolveAs(name, target)
}
// 配置服务
type ConfigService struct {
config config.Config
logger log.Logger
}
func (cs *ConfigService) GetDatabaseConfig() *DatabaseConfig {
var config DatabaseConfig
cs.config.Scan(&config)
return &config
}
func (cs *ConfigService) GetCacheConfig() *CacheConfig {
var config CacheConfig
cs.config.Scan(&config)
return &config
}
// 配置结构体
type DatabaseConfig struct {
Driver string `json:"driver" yaml:"driver"`
DSN string `json:"dsn" yaml:"dsn"`
MaxOpenConns int `json:"max_open_conns" yaml:"max_open_conns"`
MaxIdleConns int `json:"max_idle_conns" yaml:"max_idle_conns"`
ConnMaxLifetime time.Duration `json:"conn_max_lifetime" yaml:"conn_max_lifetime"`
ConnMaxIdleTime time.Duration `json:"conn_max_idle_time" yaml:"conn_max_idle_time"`
}
type CacheConfig struct {
Addr string `json:"addr" yaml:"addr"`
Password string `json:"password" yaml:"password"`
DB int `json:"db" yaml:"db"`
PoolSize int `json:"pool_size" yaml:"pool_size"`
MinIdleConns int `json:"min_idle_conns" yaml:"min_idle_conns"`
DialTimeout time.Duration `json:"dial_timeout" yaml:"dial_timeout"`
ReadTimeout time.Duration `json:"read_timeout" yaml:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout" yaml:"write_timeout"`
}
// 应用容器使用示例
func ExampleApplicationContainer() {
logger := log.NewStdLogger(os.Stdout)
// 创建应用容器
appContainer, err := NewApplicationContainer("configs/config.yaml", logger)
if err != nil {
panic(err)
}
// 注册核心服务
if err := appContainer.RegisterCoreServices(); err != nil {
panic(err)
}
// 注册业务服务
if err := appContainer.RegisterBusinessServices(); err != nil {
panic(err)
}
// 解析用户服务
userService, err := appContainer.Resolve("userService")
if err != nil {
panic(err)
}
userSvc := userService.(*UserService)
fmt.Printf("用户服务创建成功: %T\n", userSvc)
// 结构体注入示例
type App struct {
UserService UserService `inject:"userService"`
Database DatabaseService `inject:"database"`
Cache CacheService `inject:"cache"`
}
var app App
if err := appContainer.container.ResolveAll(&app); err != nil {
panic(err)
}
fmt.Printf("应用结构体注入成功: %+v\n", app)
}
---
3.3 生命周期概述
01.生命周期定义
a.生命周期概念
Kratos应用生命周期指从应用启动到停止的完整过程，包括初始化、启动、运行、停止等关键阶段，每个阶段都有明确的职责和执行顺序。
b.生命周期阶段
a.初始化阶段
应用启动前的准备工作，包括配置加载、依赖注入、资源初始化等。
b.启动阶段
服务器组件启动、服务注册、后台任务启动等操作。
c.运行阶段
应用正常运行状态，处理业务请求，执行监控和维护任务。
d.停止阶段
优雅关闭过程，包括停止接受新请求、完成现有请求、资源清理等。
02.生命周期钩子机制
a.钩子类型
a.BeforeStart钩子
在应用启动前执行，用于初始化数据库连接、缓存预热等准备工作。
b.AfterStart钩子
在应用启动后执行，用于启动后台任务、健康检查等运行时服务。
c.BeforeStop钩子
在应用停止前执行，用于停止接受新请求、保存状态等操作。
d.AfterStop钩子
在应用停止后执行，用于清理资源、关闭连接等收尾工作。
b.钩子执行顺序
a.启动流程
BeforeStart钩子 → 服务器启动 → 服务注册 → AfterStart钩子
b.停止流程
BeforeStop钩子 → 服务注销 → 服务器停止 → AfterStop钩子
c.钩子使用示例
---
// 生命周期钩子使用示例
package lifecycle
import (
"context"
"database/sql"
"fmt"
"log"
"sync"
"time"
"github.com/go-kratos/kratos/v2"
"github.com/go-kratos/kratos/v2/log"
)
// 应用生命周期管理器
type LifecycleManager struct {
app *kratos.App
db *sql.DB
cache CacheService
scheduler SchedulerService
logger log.Logger
hooks []LifecycleHook
mutex sync.RWMutex
}
// 生命周期钩子接口
type LifecycleHook interface {
Name() string
Execute(ctx context.Context) error
}
// 数据库初始化钩子
type DatabaseInitHook struct {
db *sql.DB
logger log.Logger
}
func (h *DatabaseInitHook) Name() string {
return "DatabaseInitHook"
}
func (h *DatabaseInitHook) Execute(ctx context.Context) error {
h.logger.Info("开始数据库初始化...")
// 测试数据库连接
if err := h.db.PingContext(ctx); err != nil {
return fmt.Errorf("数据库连接测试失败: %w", err)
}
// 执行数据库迁移
if err := h.runMigrations(ctx); err != nil {
return fmt.Errorf("数据库迁移失败: %w", err)
}
// 创建索引
if err := h.createIndexes(ctx); err != nil {
return fmt.Errorf("创建索引失败: %w", err)
}
h.logger.Info("数据库初始化完成")
return nil
}
func (h *DatabaseInitHook) runMigrations(ctx context.Context) error {
migrations := []string{
`CREATE TABLE IF NOT EXISTS users (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
password VARCHAR(255) NOT NULL,
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
)`,
`CREATE TABLE IF NOT EXISTS products (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(200) NOT NULL,
description TEXT,
price DECIMAL(10,2) NOT NULL,
stock INT DEFAULT 0,
status VARCHAR(20) DEFAULT 'active',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
)`,
`CREATE TABLE IF NOT EXISTS orders (
id INT PRIMARY KEY AUTO_INCREMENT,
user_id INT NOT NULL,
order_number VARCHAR(50) UNIQUE NOT NULL,
total_amount DECIMAL(10,2) NOT NULL,
status VARCHAR(20) DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (user_id) REFERENCES users(id)
)`,
}
for _, migration := range migrations {
if _, err := h.db.ExecContext(ctx, migration); err != nil {
return fmt.Errorf("执行迁移失败: %w", err)
}
}
return nil
}
func (h *DatabaseInitHook) createIndexes(ctx context.Context) error {
indexes := []string{
"CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)",
"CREATE INDEX IF NOT EXISTS idx_users_status ON users(status)",
"CREATE INDEX IF NOT EXISTS idx_products_status ON products(status)",
"CREATE INDEX IF NOT EXISTS idx_orders_user_id ON orders(user_id)",
"CREATE INDEX IF NOT EXISTS idx_orders_status ON orders(status)",
"CREATE INDEX IF NOT EXISTS idx_orders_created_at ON orders(created_at)",
}
for _, index := range indexes {
if _, err := h.db.ExecContext(ctx, index); err != nil {
return fmt.Errorf("创建索引失败: %w", err)
}
}
return nil
}
// 缓存预热钩子
type CacheWarmupHook struct {
cache CacheService
userRepo UserRepository
logger log.Logger
}
func (h *CacheWarmupHook) Name() string {
return "CacheWarmupHook"
}
func (h *CacheWarmupHook) Execute(ctx context.Context) error {
h.logger.Info("开始缓存预热...")
// 预热热点数据
hotKeys := []string{
"config:system",
"config:features",
"user:permissions:admin",
"product:categories",
"payment:methods",
}
for _, key := range hotKeys {
if err := h.warmupKey(ctx, key); err != nil {
h.logger.Warnf("预热缓存失败: key=%s, error=%v", key, err)
}
}
// 预热用户数据
if err := h.warmupUsers(ctx); err != nil {
h.logger.Warnf("预热用户数据失败: %v", err)
}
h.logger.Info("缓存预热完成")
return nil
}
func (h *CacheWarmupHook) warmupKey(ctx context.Context, key string) error {
// 检查缓存中是否存在
if _, err := h.cache.Get(key); err == nil {
return nil // 已存在，无需预热
}
// 根据key类型加载相应的数据
var value interface{}
switch {
case key == "config:system":
value = h.loadSystemConfig()
case key == "config:features":
value = h.loadFeatureConfig()
case key == "user:permissions:admin":
value = h.loadAdminPermissions()
case key == "product:categories":
value = h.loadProductCategories()
case key == "payment:methods":
value = h.loadPaymentMethods()
default:
return nil
}
// 设置缓存，过期时间30分钟
return h.cache.Set(key, value, 30*time.Minute)
}
func (h *CacheWarmupHook) warmupUsers(ctx context.Context) error {
// 获取活跃用户列表
activeUsers, err := h.userRepo.GetActiveUsers(ctx, 100) // 限制预热数量
if err != nil {
return fmt.Errorf("获取活跃用户失败: %w", err)
}
// 预热用户信息
for _, user := range activeUsers {
key := fmt.Sprintf("user:%d", user.ID)
if err := h.cache.Set(key, user, 15*time.Minute); err != nil {
h.logger.Warnf("预热用户缓存失败: key=%s, error=%v", key, err)
}
}
return nil
}
// 后台任务启动钩子
type BackgroundTasksHook struct {
tasks []BackgroundTask
logger log.Logger
stopChan chan struct{}
wg sync.WaitGroup
}
func (h *BackgroundTasksHook) Name() string {
return "BackgroundTasksHook"
}
func (h *BackgroundTasksHook) Execute(ctx context.Context) error {
h.logger.Info("启动后台任务...")
h.stopChan = make(chan struct{})
for _, task := range h.tasks {
h.wg.Add(1)
go func(t BackgroundTask) {
defer h.wg.Done()
h.runTask(ctx, t)
}(task)
}
h.logger.Infof("已启动 %d 个后台任务", len(h.tasks))
return nil
}
func (h *BackgroundTasksHook) runTask(ctx context.Context, task BackgroundTask) {
taskName := task.Name()
h.logger.Infof("启动后台任务: %s", taskName)
ticker := time.NewTicker(task.Interval())
defer ticker.Stop()
for {
select {
case <-ctx.Done():
h.logger.Infof("停止后台任务: %s", taskName)
return
case <-ticker.C:
if err := task.Execute(ctx); err != nil {
h.logger.Errorf("后台任务执行失败: task=%s, error=%v", taskName, err)
}
}
}
}
func (h *BackgroundTasksHook) Stop() {
if h.stopChan != nil {
close(h.stopChan)
h.wg.Wait()
h.logger.Info("所有后台任务已停止")
}
}
// 健康检查启动钩子
type HealthCheckHook struct {
checker *HealthChecker
logger log.Logger
}
func (h *HealthCheckHook) Name() string {
return "HealthCheckHook"
}
func (h *HealthCheckHook) Execute(ctx context.Context) error {
h.logger.Info("启动健康检查服务...")
// 启动健康检查端点
go h.startHealthCheckServer(ctx)
// 注册健康检查指标
h.registerHealthMetrics()
h.logger.Info("健康检查服务启动完成")
return nil
}
func (h *HealthCheckHook) startHealthCheckServer(ctx context.Context) {
http.HandleFunc("/health", h.healthHandler)
http.HandleFunc("/ready", h.readinessHandler)
http.HandleFunc("/live", h.livenessHandler)
server := &http.Server{
Addr: ":8090",
Handler: nil,
}
go func() {
if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
h.logger.Errorf("健康检查服务器启动失败: %v", err)
}
}()
// 监听停止信号
<-ctx.Done()
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := server.Shutdown(shutdownCtx); err != nil {
h.logger.Errorf("健康检查服务器关闭失败: %v", err)
}
}
func (h *HealthCheckHook) healthHandler(w http.ResponseWriter, r *http.Request) {
status := h.checker.HealthStatus()
w.Header().Set("Content-Type", "application/json")
if status.IsHealthy {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(status)
}
func (h *HealthCheckHook) readinessHandler(w http.ResponseWriter, r *http.Request) {
status := h.checker.ReadinessStatus()
w.Header().Set("Content-Type", "application/json")
if status.IsReady {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(status)
}
func (h *HealthCheckHook) livenessHandler(w http.ResponseWriter, r *http.Request) {
status := h.checker.LivenessStatus()
w.Header().Set("Content-Type", "application/json")
if status.IsAlive {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(status)
}
// 优雅关闭钩子
type GracefulShutdownHook struct {
servers []Server
timeout time.Duration
logger log.Logger
}
func (h *GracefulShutdownHook) Name() string {
return "GracefulShutdownHook"
}
func (h *GracefulShutdownHook) Execute(ctx context.Context) error {
h.logger.Info("开始优雅关闭...")
// 创建带超时的上下文
shutdownCtx, cancel := context.WithTimeout(ctx, h.timeout)
defer cancel()
// 逐个停止服务器
for _, server := range h.servers {
if err := h.stopServer(shutdownCtx, server); err != nil {
h.logger.Errorf("停止服务器失败: server=%s, error=%v", server.Name(), err)
// 继续停止其他服务器
}
}
h.logger.Info("优雅关闭完成")
return nil
}
func (h *GracefulShutdownHook) stopServer(ctx context.Context, server Server) error {
h.logger.Infof("停止服务器: %s", server.Name())
done := make(chan error, 1)
go func() {
done <- server.Stop(ctx)
}()
select {
case err := <-done:
if err != nil {
return fmt.Errorf("停止服务器失败: %w", err)
}
h.logger.Infof("服务器已停止: %s", server.Name())
return nil
case <-ctx.Done():
return fmt.Errorf("停止服务器超时: %s", server.Name())
}
}
// 资源清理钩子
type ResourceCleanupHook struct {
resources []Resource
logger log.Logger
}
func (h *ResourceCleanupHook) Name() string {
return "ResourceCleanupHook"
}
func (h *ResourceCleanupHook) Execute(ctx context.Context) error {
h.logger.Info("开始资源清理...")
var errors []error
for _, resource := range h.resources {
if err := h.cleanupResource(ctx, resource); err != nil {
h.logger.Errorf("清理资源失败: resource=%T, error=%v", resource, err)
errors = append(errors, err)
}
}
if len(errors) > 0 {
return fmt.Errorf("资源清理时发生错误: %v", errors)
}
h.logger.Info("资源清理完成")
return nil
}
func (h *ResourceCleanupHook) cleanupResource(ctx context.Context, resource Resource) error {
resourceName := fmt.Sprintf("%T", resource)
h.logger.Infof("清理资源: %s", resourceName)
if err := resource.Cleanup(ctx); err != nil {
return fmt.Errorf("清理资源失败: resource=%s, error=%w", resourceName, err)
}
h.logger.Infof("资源清理完成: %s", resourceName)
return nil
}
// 生命周期管理器使用示例
func ExampleLifecycleManager() {
// 创建日志记录器
logger := log.NewStdLogger(os.Stdout)
// 创建数据库连接
db, err := sql.Open("mysql", "user:password@tcp(localhost:3306)/dbname")
if err != nil {
panic(err)
}
// 创建缓存服务
cache := NewCacheService()
// 创建用户仓储
userRepo := NewUserRepository(db, cache, logger)
// 创建后台任务
tasks := []BackgroundTask{
NewMetricsCollector(),
NewCleanupTask(),
NewDataSyncTask(),
}
// 创建健康检查器
healthChecker := NewHealthChecker(db, cache)
// 创建资源列表
resources := []Resource{
db,
cache,
NewMessageQueue(),
}
// 创建服务器列表
servers := []Server{
NewHTTPServer(":8080"),
NewGRPCServer(":9090"),
}
// 创建生命周期钩子
hooks := []kratos.Option{
kratos.BeforeStart(NewDatabaseInitHook(db, logger).Execute),
kratos.BeforeStart(NewCacheWarmupHook(cache, userRepo, logger).Execute),
kratos.AfterStart(NewBackgroundTasksHook(tasks, logger).Execute),
kratos.AfterStart(NewHealthCheckHook(healthChecker, logger).Execute),
kratos.BeforeStop(NewGracefulShutdownHook(servers, 30*time.Second, logger).Execute),
kratos.AfterStop(NewResourceCleanupHook(resources, logger).Execute),
}
// 创建应用
app := kratos.New(
kratos.ID("user-service"),
kratos.Name("user-service"),
kratos.Version("v1.0.0"),
kratos.Metadata(map[string]string{
"env": "production",
"region": "us-west-1",
"zone": "us-west-1a",
}),
kratos.Server(
servers[0].(*HTTPServer),
servers[1].(*GRPCServer),
),
hooks...,
)
// 启动应用
if err := app.Run(context.Background()); err != nil {
logger.Errorf("应用运行失败: %v", err)
}
}
// 接口定义
type CacheService interface {
Get(key string) (interface{}, error)
Set(key string, value interface{}, expiration time.Duration) error
Delete(key string) error
}
type UserRepository interface {
GetActiveUsers(ctx context.Context, limit int) ([]*User, error)
}
type BackgroundTask interface {
Name() string
Execute(ctx context.Context) error
Interval() time.Duration
}
type Resource interface {
Cleanup(ctx context.Context) error
}
type Server interface {
Name() string
Stop(ctx context.Context) error
}
type HealthChecker struct {
db *sql.DB
cache CacheService
}
func (h *HealthChecker) HealthStatus() *HealthStatus {
return &HealthStatus{IsHealthy: true}
}
func (h *HealthChecker) ReadinessStatus() *ReadinessStatus {
return &ReadinessStatus{IsReady: true}
}
func (h *HealthChecker) LivenessStatus() *LivenessStatus {
return &LivenessStatus{IsAlive: true}
}
type HealthStatus struct {
IsHealthy bool `json:"healthy"`
}
type ReadinessStatus struct {
IsReady bool `json:"ready"`
}
type LivenessStatus struct {
IsAlive bool `json:"alive"`
}
// 辅助函数和结构体
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// 钩子辅助函数
func (h *CacheWarmupHook) loadSystemConfig() interface{} {
return map[string]interface{}{
"app_name": "user-service",
"version": "1.0.0",
"environment": "production",
"debug": false,
}
}
func (h *CacheWarmupHook) loadFeatureConfig() interface{} {
return map[string]bool{
"user_registration": true,
"email_verification": true,
"social_login": true,
"mfa_enabled": false,
}
}
func (h *CacheWarmupHook) loadAdminPermissions() interface{} {
return []string{
"user:read",
"user:write",
"user:delete",
"system:admin",
"metrics:view",
}
}
func (h *CacheWarmupHook) loadProductCategories() interface{} {
return []string{
"Electronics",
"Clothing",
"Books",
"Home",
"Sports",
}
}
func (h *CacheWarmupHook) loadPaymentMethods() interface{} {
return []string{
"credit_card",
"debit_card",
"paypal",
"bank_transfer",
"cryptocurrency",
}
}
func (h *HealthCheckHook) registerHealthMetrics() {
// 注册健康检查相关指标的逻辑
}
// 示例任务实现
type MetricsCollector struct{}
func (m *MetricsCollector) Name() string {
return "MetricsCollector"
}
func (m *MetricsCollector) Execute(ctx context.Context) error {
// 收集应用指标的逻辑
return nil
}
func (m *MetricsCollector) Interval() time.Duration {
return 30 * time.Second
}
type CleanupTask struct{}
func (c *CleanupTask) Name() string {
return "CleanupTask"
}
func (c *CleanupTask) Execute(ctx context.Context) error {
// 执行清理任务的逻辑
return nil
}
func (c *CleanupTask) Interval() time.Duration {
return 1 * time.Hour
}
type DataSyncTask struct{}
func (d *DataSyncTask) Name() string {
return "DataSyncTask"
}
func (d *DataSyncTask) Execute(ctx context.Context) error {
// 执行数据同步任务的逻辑
return nil
}
func (d *DataSyncTask) Interval() time.Duration {
return 5 * time.Minute
}
// 辅助构造函数
func NewCacheService() CacheService {
// 返回缓存服务实例
return nil
}
func NewUserRepository(db *sql.DB, cache CacheService, logger log.Logger) UserRepository {
// 返回用户仓储实例
return nil
}
func NewMetricsCollector() BackgroundTask {
return &MetricsCollector{}
}
func NewCleanupTask() BackgroundTask {
return &CleanupTask{}
}
func NewDataSyncTask() BackgroundTask {
return &DataSyncTask{}
}
func NewHealthChecker(db *sql.DB, cache CacheService) *HealthChecker {
return &HealthChecker{
db: db,
cache: cache,
}
}
func NewMessageQueue() Resource {
// 返回消息队列实例
return nil
}
func NewHTTPServer(addr string) Server {
// 返回HTTP服务器实例
return nil
}
func NewGRPCServer(addr string) Server {
// 返回gRPC服务器实例
return nil
}
---
3.4 应用初始化
01.初始化流程概述
a.初始化阶段定义
应用初始化是Kratos应用生命周期的第一个阶段，负责准备应用运行所需的所有资源和环境，为后续的服务启动做好充分准备。
b.初始化核心任务
a.配置加载与解析
从多种来源加载应用配置，包括配置文件、环境变量、命令行参数等，并进行验证和合并。
b.依赖注入容器初始化
创建并配置依赖注入容器，注册基础服务和组件。
c.数据库连接建立
建立数据库连接池，执行连接测试和基础表结构验证。
d.中间件链构建
根据配置构建HTTP和gRPC服务器的中间件链。
e.健康检查初始化
设置健康检查端点和相关监控组件。
02.配置加载与解析
a.配置源管理
a.多层级配置系统
支持默认配置、文件配置、环境变量配置的分层覆盖机制，优先级从低到高。
b.配置文件格式
支持JSON、YAML、TOML等多种配置文件格式，可根据环境选择不同格式。
c.动态配置
支持配置热更新，无需重启应用即可生效。
b.配置加载实现
a.代码示例
---
// 配置加载与解析实现示例
package config
import (
"context"
"fmt"
"os"
"reflect"
"strconv"
"strings"
"time"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/config/env"
"github.com/go-kratos/kratos/v2/log"
)
// 配置管理器
type ConfigManager struct {
config config.Config
logger log.Logger
validator ConfigValidator
watcher ConfigWatcher
}
// 配置验证器接口
type ConfigValidator interface {
Validate(cfg interface{}) error
}
// 配置观察者接口
type ConfigWatcher interface {
Watch(key string, callback func(oldValue, newValue interface{})) error
Stop() error
}
// 创建配置管理器
func NewConfigManager(configPath string, logger log.Logger) (*ConfigManager, error) {
// 创建配置源
sources := buildConfigSources(configPath)
// 创建配置实例
c := config.New(
config.WithSource(sources...),
config.WithDecoder(configDecoder),
)
// 加载配置
if err := c.Load(); err != nil {
return nil, fmt.Errorf("加载配置失败: %w", err)
}
return &ConfigManager{
config: c,
logger: logger,
validator: NewDefaultConfigValidator(),
watcher: NewConfigWatcher(c, logger),
}, nil
}
// 构建配置源
func buildConfigSources(configPath string) []config.Source {
var sources []config.Source
// 1. 默认配置源（最低优先级）
defaultConfig := map[string]interface{}{
"server": map[string]interface{}{
"http": map[string]interface{}{
"addr": ":8080",
"timeout": "30s",
},
"grpc": map[string]interface{}{
"addr": ":9090",
"timeout": "30s",
},
},
"log": map[string]interface{}{
"level": "info",
"format": "json",
},
}
sources = append(sources, config.NewSource(defaultConfig))
// 2. 文件配置源
if configPath != "" {
sources = append(sources, file.NewSource(configPath))
}
// 3. 环境变量配置源（最高优先级）
sources = append(sources, env.NewSource("KRATOS_"))
return sources
}
// 自定义配置解码器
func configDecoder(kv *config.KeyValue, v interface{}) error {
// 根据配置键的类型选择解码策略
switch kv.Key {
case "database.max_open_conns":
return decodeInt(kv, v)
case "database.conn_max_lifetime":
return decodeDuration(kv, v)
case "server.http.timeout":
return decodeDuration(kv, v)
case "server.grpc.timeout":
return decodeDuration(kv, v)
default:
return config.DefaultDecoder(kv, v)
}
}
// 整数解码器
func decodeInt(kv *config.KeyValue, v interface{}) error {
strValue := strings.TrimSpace(kv.Value.(string))
intValue, err := strconv.Atoi(strValue)
if err != nil {
return fmt.Errorf("无法将 %s 转换为整数: %w", kv.Key, err)
}
// 使用反射设置值
rv := reflect.ValueOf(v)
if rv.Kind() == reflect.Ptr {
rv = rv.Elem()
}
if rv.Kind() == reflect.Int {
rv.SetInt(int64(intValue))
return nil
}
return fmt.Errorf("目标类型不是整数")
}
// 时间段解码器
func decodeDuration(kv *config.KeyValue, v interface{}) error {
strValue := strings.TrimSpace(kv.Value.(string))
duration, err := time.ParseDuration(strValue)
if err != nil {
return fmt.Errorf("无法将 %s 转换为时间段: %w", kv.Key, err)
}
// 使用反射设置值
rv := reflect.ValueOf(v)
if rv.Kind() == reflect.Ptr {
rv = rv.Elem()
}
if rv.Type() == reflect.TypeOf(time.Duration(0)) {
rv.Set(reflect.ValueOf(duration))
return nil
}
return fmt.Errorf("目标类型不是时间段")
}
// 配置结构体
type AppConfig struct {
Name string `json:"name" yaml:"name"`
Version string `json:"version" yaml:"version"`
Env string `json:"env" yaml:"env"`
Debug bool `json:"debug" yaml:"debug"`
Server ServerConfig `json:"server" yaml:"server"`
Data DataConfig `json:"data" yaml:"data"`
Log LogConfig `json:"log" yaml:"log"`
Auth AuthConfig `json:"auth" yaml:"auth"`
Metrics MetricsConfig `json:"metrics" yaml:"metrics"`
}
type ServerConfig struct {
HTTP HTTPServerConfig `json:"http" yaml:"http"`
GRPC GRPCServerConfig `json:"grpc" yaml:"grpc"`
}
type HTTPServerConfig struct {
Addr string `json:"addr" yaml:"addr"`
Timeout time.Duration `json:"timeout" yaml:"timeout"`
ReadTimeout time.Duration `json:"read_timeout" yaml:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout" yaml:"write_timeout"`
IdleTimeout time.Duration `json:"idle_timeout" yaml:"idle_timeout"`
}
type GRPCServerConfig struct {
Addr string `json:"addr" yaml:"addr"`
Timeout time.Duration `json:"timeout" yaml:"timeout"`
MaxRecvMsgSize int `json:"max_recv_msg_size" yaml:"max_recv_msg_size"`
MaxSendMsgSize int `json:"max_send_msg_size" yaml:"max_send_msg_size"`
MaxConcurrentStreams int `json:"max_concurrent_streams" yaml:"max_concurrent_streams"`
}
type DataConfig struct {
Database DatabaseConfig `json:"database" yaml:"database"`
Redis RedisConfig `json:"redis" yaml:"redis"`
}
type DatabaseConfig struct {
Driver string `json:"driver" yaml:"driver"`
DSN string `json:"dsn" yaml:"dsn"`
MaxOpenConns int `json:"max_open_conns" yaml:"max_open_conns"`
MaxIdleConns int `json:"max_idle_conns" yaml:"max_idle_conns"`
ConnMaxLifetime time.Duration `json:"conn_max_lifetime" yaml:"conn_max_lifetime"`
ConnMaxIdleTime time.Duration `json:"conn_max_idle_time" yaml:"conn_max_idle_time"`
}
type RedisConfig struct {
Addr string `json:"addr" yaml:"addr"`
Password string `json:"password" yaml:"password"`
DB int `json:"db" yaml:"db"`
PoolSize int `json:"pool_size" yaml:"pool_size"`
MinIdleConns int `json:"min_idle_conns" yaml:"min_idle_conns"`
DialTimeout time.Duration `json:"dial_timeout" yaml:"dial_timeout"`
ReadTimeout time.Duration `json:"read_timeout" yaml:"read_timeout"`
WriteTimeout time.Duration `json:"write_timeout" yaml:"write_timeout"`
}
type LogConfig struct {
Level string `json:"level" yaml:"level"`
Format string `json:"format" yaml:"format"`
Output string `json:"output" yaml:"output"`
Filename string `json:"filename" yaml:"filename"`
MaxSize int `json:"max_size" yaml:"max_size"`
MaxAge int `json:"max_age" yaml:"max_age"`
MaxBackups int `json:"max_backups" yaml:"max_backups"`
Compress bool `json:"compress" yaml:"compress"`
}
type AuthConfig struct {
JWTSecret string `json:"jwt_secret" yaml:"jwt_secret"`
JWTExpire time.Duration `json:"jwt_expire" yaml:"jwt_expire"`
RefreshExpire time.Duration `json:"refresh_expire" yaml:"refresh_expire"`
BCryptCost int `json:"bcrypt_cost" yaml:"bcrypt_cost"`
}
type MetricsConfig struct {
Enabled bool `json:"enabled" yaml:"enabled"`
Addr string `json:"addr" yaml:"addr"`
Path string `json:"path" yaml:"path"`
Namespace string `json:"namespace" yaml:"namespace"`
Subsystem string `json:"subsystem" yaml:"subsystem"`
}
// 加载应用配置
func (cm *ConfigManager) LoadAppConfig() (*AppConfig, error) {
var config AppConfig
// 扫描配置到结构体
if err := cm.config.Scan(&config); err != nil {
return nil, fmt.Errorf("扫描配置失败: %w", err)
}
// 设置默认值
cm.setDefaults(&config)
// 验证配置
if err := cm.validator.Validate(&config); err != nil {
return nil, fmt.Errorf("配置验证失败: %w", err)
}
// 记录配置信息（隐藏敏感信息）
cm.logConfig(&config)
return &config, nil
}
// 设置默认值
func (cm *ConfigManager) setDefaults(config *AppConfig) {
if config.Name == "" {
config.Name = "kratos-service"
}
if config.Version == "" {
config.Version = "1.0.0"
}
if config.Env == "" {
config.Env = "development"
}
if config.Server.HTTP.Addr == "" {
config.Server.HTTP.Addr = ":8080"
}
if config.Server.HTTP.Timeout == 0 {
config.Server.HTTP.Timeout = 30 * time.Second
}
if config.Server.GRPC.Addr == "" {
config.Server.GRPC.Addr = ":9090"
}
if config.Server.GRPC.Timeout == 0 {
config.Server.GRPC.Timeout = 30 * time.Second
}
if config.Data.Database.MaxOpenConns == 0 {
config.Data.Database.MaxOpenConns = 100
}
if config.Data.Database.MaxIdleConns == 0 {
config.Data.Database.MaxIdleConns = 10
}
if config.Data.Database.ConnMaxLifetime == 0 {
config.Data.Database.ConnMaxLifetime = time.Hour
}
if config.Log.Level == "" {
config.Log.Level = "info"
}
if config.Auth.JWTExpire == 0 {
config.Auth.JWTExpire = 24 * time.Hour
}
if config.Auth.BCryptCost == 0 {
config.Auth.BCryptCost = 10
}
}
// 记录配置信息（隐藏敏感信息）
func (cm *ConfigManager) logConfig(config *AppConfig) {
cm.logger.Infof("应用配置加载完成:")
cm.logger.Infof(" 名称: %s", config.Name)
cm.logger.Infof(" 版本: %s", config.Version)
cm.logger.Infof(" 环境: %s", config.Env)
cm.logger.Infof(" 调试模式: %t", config.Debug)
cm.logger.Infof(" HTTP服务器: %s", config.Server.HTTP.Addr)
cm.logger.Infof(" gRPC服务器: %s", config.Server.GRPC.Addr)
cm.logger.Infof(" 数据库驱动: %s", config.Data.Database.Driver)
cm.logger.Infof(" 日志级别: %s", config.Log.Level)
cm.logger.Infof(" 指标收集: %t", config.Metrics.Enabled)
// 隐藏敏感信息
if config.Data.Redis.Password != "" {
cm.logger.Infof(" Redis密码: ********")
}
if config.Auth.JWTSecret != "" {
cm.logger.Infof(" JWT密钥: ********")
}
}
// 监听配置变更
func (cm *ConfigManager) WatchConfig(key string, callback func(oldValue, newValue interface{})) error {
return cm.watcher.Watch(key, callback)
}
// 重新加载配置
func (cm *ConfigManager) ReloadConfig() error {
if err := cm.config.Load(); err != nil {
return fmt.Errorf("重新加载配置失败: %w", err)
}
cm.logger.Info("配置重新加载成功")
return nil
}
// 配置管理器使用示例
func ExampleConfigManager() {
logger := log.NewStdLogger(os.Stdout)
// 创建配置管理器
configManager, err := NewConfigManager("configs/config.yaml", logger)
if err != nil {
panic(err)
}
// 加载应用配置
appConfig, err := configManager.LoadAppConfig()
if err != nil {
panic(err)
}
// 监听配置变更
err = configManager.WatchConfig("server.http.addr", func(oldValue, newValue interface{}) {
logger.Infof("HTTP服务器地址变更: %s -> %s", oldValue, newValue)
})
if err != nil {
logger.Errorf("监听配置变更失败: %v", err)
}
// 重新加载配置
err = configManager.ReloadConfig()
if err != nil {
logger.Errorf("重新加载配置失败: %v", err)
}
}
---
03.依赖注入容器初始化
a.容器创建与配置
a.容器生命周期管理
依赖注入容器管理所有服务的生命周期，包括单例服务和瞬态服务，提供类型安全的依赖解析。
b.服务注册策略
按照依赖关系顺序注册服务，确保被依赖的服务先于依赖者注册。
c.循环依赖检测
在服务注册和解析过程中检测并报告循环依赖问题。
b.容器初始化实现
a.代码示例
---
// 依赖注入容器初始化示例
package container
import (
"context"
"fmt"
"reflect"
"sync"
"time"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/config"
)
// 应用容器
type ApplicationContainer struct {
container Container
logger log.Logger
config *AppConfig
mutex sync.RWMutex
initializing bool
initialized bool
initErrors []error
initCallbacks []InitCallback
}
// 初始化回调接口
type InitCallback interface {
Name() string
Priority() int
Execute(ctx context.Context, container Container) error
}
// 创建应用容器
func NewApplicationContainer(logger log.Logger) *ApplicationContainer {
return &ApplicationContainer{
container: NewContainer(),
logger: logger,
initCallbacks: make([]InitCallback, 0),
initErrors: make([]error, 0),
}
}
// 设置配置
func (ac *ApplicationContainer) SetConfig(config *AppConfig) {
ac.config = config
}
// 添加初始化回调
func (ac *ApplicationContainer) AddInitCallback(callback InitCallback) {
ac.mutex.Lock()
defer ac.mutex.Unlock()
if ac.initialized {
ac.logger.Warnf("容器已初始化，无法添加回调: %s", callback.Name())
return
}
ac.initCallbacks = append(ac.initCallbacks, callback)
ac.logger.Infof("添加初始化回调: %s (优先级: %d)", callback.Name(), callback.Priority())
}
// 初始化容器
func (ac *ApplicationContainer) Initialize(ctx context.Context) error {
ac.mutex.Lock()
defer ac.mutex.Unlock()
if ac.initializing {
return fmt.Errorf("容器正在初始化中")
}
if ac.initialized {
ac.logger.Warn("容器已经初始化")
return nil
}
ac.initializing = true
ac.initErrors = make([]error, 0)
ac.logger.Info("开始初始化依赖注入容器...")
// 1. 按优先级排序回调
callbacks := ac.sortCallbacks()
// 2. 执行初始化回调
for i, callback := range callbacks {
ac.logger.Infof("执行初始化回调 [%d/%d]: %s", i+1, len(callbacks), callback.Name())
if err := callback.Execute(ctx, ac.container); err != nil {
ac.logger.Errorf("初始化回调执行失败: name=%s, error=%v", callback.Name(), err)
ac.initErrors = append(ac.initErrors, fmt.Errorf("%s: %w", callback.Name(), err))
// 根据配置决定是否继续初始化
if ac.config != nil && !ac.config.Debug {
ac.initializing = false
return fmt.Errorf("初始化失败: %v", ac.initErrors)
}
}
}
// 3. 验证容器状态
if err := ac.validateContainer(); err != nil {
ac.initErrors = append(ac.initErrors, err)
}
// 4. 记录初始化结果
ac.logInitializationResult()
ac.initializing = false
ac.initialized = true
if len(ac.initErrors) > 0 {
return fmt.Errorf("容器初始化完成，但有 %d 个错误: %v", len(ac.initErrors), ac.initErrors)
}
ac.logger.Info("依赖注入容器初始化成功")
return nil
}
// 排序回调（按优先级）
func (ac *ApplicationContainer) sortCallbacks() []InitCallback {
callbacks := make([]InitCallback, len(ac.initCallbacks))
copy(callbacks, ac.initCallbacks)
// 按优先级排序（数字越小优先级越高）
for i := 0; i < len(callbacks)-1; i++ {
for j := i + 1; j < len(callbacks); j++ {
if callbacks[i].Priority() > callbacks[j].Priority() {
callbacks[i], callbacks[j] = callbacks[j], callbacks[i]
}
}
}
return callbacks
}
// 验证容器状态
func (ac *ApplicationContainer) validateContainer() error {
// 检查关键服务是否已注册
criticalServices := []string{
"logger",
"config",
"database",
}
for _, serviceName := range criticalServices {
if _, err := ac.container.Resolve(serviceName); err != nil {
return fmt.Errorf("关键服务未注册: %s", serviceName)
}
}
// 检查服务依赖关系
if err := ac.validateDependencies(); err != nil {
return fmt.Errorf("服务依赖验证失败: %w", err)
}
return nil
}
// 验证服务依赖关系
func (ac *ApplicationContainer) validateDependencies() error {
// 检查循环依赖
visiting := make(map[string]bool)
visited := make(map[string]bool)
services := ac.container.ListServices()
for _, serviceName := range services {
if err := ac.checkDependency(serviceName, visiting, visited); err != nil {
return err
}
}
return nil
}
// 检查单个服务的依赖关系
func (ac *ApplicationContainer) checkDependency(serviceName string, visiting, visited map[string]bool) error {
if visited[serviceName] {
return nil
}
if visiting[serviceName] {
return fmt.Errorf("检测到循环依赖: %s", serviceName)
}
visiting[serviceName] = true
// 获取服务的依赖
dependencies := ac.container.GetDependencies(serviceName)
for _, dep := range dependencies {
if err := ac.checkDependency(dep, visiting, visited); err != nil {
return err
}
}
delete(visiting, serviceName)
visited[serviceName] = true
return nil
}
// 记录初始化结果
func (ac *ApplicationContainer) logInitializationResult() {
services := ac.container.ListServices()
ac.logger.Infof("容器初始化完成，共注册 %d 个服务:", len(services))
for _, service := range services {
singleton := ac.container.IsSingleton(service)
ac.logger.Infof(" - %s (%s)", service, func() string {
if singleton {
return "单例"
}
return "瞬态"
}())
}
if len(ac.initErrors) > 0 {
ac.logger.Warnf("初始化过程中发生 %d 个错误:", len(ac.initErrors))
for i, err := range ac.initErrors {
ac.logger.Warnf(" [%d] %v", i+1, err)
}
}
}
// 获取服务
func (ac *ApplicationContainer) GetService(name string) (interface{}, error) {
if !ac.initialized {
return nil, fmt.Errorf("容器未初始化")
}
return ac.container.Resolve(name)
}
// 检查是否已初始化
func (ac *ApplicationContainer) IsInitialized() bool {
ac.mutex.RLock()
defer ac.mutex.RUnlock()
return ac.initialized
}
// 获取初始化错误
func (ac *ApplicationContainer) GetInitErrors() []error {
ac.mutex.RLock()
defer ac.mutex.RUnlock()
return append([]error(nil), ac.initErrors...)
}
// 基础服务初始化回调
type LoggerInitCallback struct{}
func (lic *LoggerInitCallback) Name() string {
return "LoggerInit"
}
func (lic *LoggerInitCallback) Priority() int {
return 100 // 最高优先级
}
func (lic *LoggerInitCallback) Execute(ctx context.Context, container Container) error {
logger := log.NewStdLogger(os.Stdout)
return container.RegisterSingleton("logger", func(c Container) (interface{}, error) {
return logger, nil
})
}
type ConfigInitCallback struct {
config *AppConfig
}
func (cic *ConfigInitCallback) Name() string {
return "ConfigInit"
}
func (cic *ConfigInitCallback) Priority() int {
return 90
}
func (cic *ConfigInitCallback) Execute(ctx context.Context, container Container) error {
return container.RegisterSingleton("config", func(c Container) (interface{}, error) {
return cic.config, nil
})
}
type DatabaseInitCallback struct {
config *DatabaseConfig
logger log.Logger
}
func (dic *DatabaseInitCallback) Name() string {
return "DatabaseInit"
}
func (dic *DatabaseInitCallback) Priority() int {
return 70
}
func (dic *DatabaseInitCallback) Execute(ctx context.Context, container Container) error {
return container.RegisterSingleton("database", func(c Container) (interface{}, error) {
return NewDatabaseService(dic.config, dic.logger)
})
}
type CacheInitCallback struct {
config *RedisConfig
logger log.Logger
}
func (cic *CacheInitCallback) Name() string {
return "CacheInit"
}
func (cic *CacheInitCallback) Priority() int {
return 60
}
func (cic *CacheInitCallback) Execute(ctx context.Context, container Container) error {
return container.RegisterSingleton("cache", func(c Container) (interface{}, error) {
return NewCacheService(cic.config, cic.logger)
})
}
// 应用容器初始化示例
func ExampleApplicationContainerInit() {
logger := log.NewStdLogger(os.Stdout)
// 创建应用容器
container := NewApplicationContainer(logger)
// 设置配置
config := &AppConfig{
Name: "user-service",
Version: "1.0.0",
Env: "production",
Debug: false,
Data: DataConfig{
Database: DatabaseConfig{
Driver: "mysql",
DSN: "user:password@tcp(localhost:3306)/users",
MaxOpenConns: 100,
MaxIdleConns: 10,
ConnMaxLifetime: time.Hour,
},
Redis: RedisConfig{
Addr: "localhost:6379",
Password: "",
DB: 0,
PoolSize: 100,
},
},
}
container.SetConfig(config)
// 添加初始化回调
container.AddInitCallback(&LoggerInitCallback{})
container.AddInitCallback(&ConfigInitCallback{config: config})
container.AddInitCallback(&DatabaseInitCallback{
config: &config.Data.Database,
logger: logger,
})
container.AddInitCallback(&CacheInitCallback{
config: &config.Data.Redis,
logger: logger,
})
// 初始化容器
ctx := context.Background()
if err := container.Initialize(ctx); err != nil {
logger.Errorf("容器初始化失败: %v", err)
return
}
// 获取服务
databaseService, err := container.GetService("database")
if err != nil {
logger.Errorf("获取数据库服务失败: %v", err)
return
}
cacheService, err := container.GetService("cache")
if err != nil {
logger.Errorf("获取缓存服务失败: %v", err)
return
}
logger.Infof("服务获取成功:")
logger.Infof(" 数据库服务: %T", databaseService)
logger.Infof(" 缓存服务: %T", cacheService)
// 检查初始化错误
if errors := container.GetInitErrors(); len(errors) > 0 {
logger.Warnf("发现 %d 个初始化错误:", len(errors))
for i, err := range errors {
logger.Warnf(" [%d] %v", i+1, err)
}
}
}
// 辅助构造函数
func NewDatabaseService(config *DatabaseConfig, logger log.Logger) interface{} {
// 返回数据库服务实例
return &DatabaseService{config: config, logger: logger}
}
func NewCacheService(config *RedisConfig, logger log.Logger) interface{} {
// 返回缓存服务实例
return &CacheService{config: config, logger: logger}
}
// 服务类型定义
type DatabaseService struct {
config *DatabaseConfig
logger log.Logger
}
type CacheService struct {
config *RedisConfig
logger log.Logger
}
---
3.5 服务器启动
01.服务器启动流程
a.启动阶段定义
服务器启动是Kratos应用生命周期的核心阶段，负责创建和启动HTTP/gRPC服务器实例，建立网络监听，开始处理客户端请求。
b.启动步骤
a.服务器实例创建
根据配置创建HTTP和gRPC服务器实例，设置相应的中间件链和处理器。
b.端口绑定与监听
绑定指定端口并开始监听网络连接。
c.服务注册
向服务注册中心注册服务实例，使其可被其他服务发现。
d.健康检查启动
启动健康检查服务，提供应用状态查询接口。
02.HTTP服务器启动
a.启动配置
a.网络配置
设置监听地址、端口、超时时间等网络参数。
b.中间件配置
配置恢复、日志、监控、认证等中间件链。
c.路由配置
注册HTTP路由和处理器，支持RESTful API设计。
b.启动实现
a.代码示例
---
// HTTP服务器启动实现示例
package server
import (
"context"
"fmt"
"net"
"net/http"
"time"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
)
// HTTP服务器启动器
type HTTPServerStarter struct {
config *HTTPServerConfig
logger log.Logger
middleware []http.ServerMiddleware
routers []http.Router
services []HTTPService
hooks []ServerHook
server *http.Server
started bool
mutex sync.RWMutex
}
// 服务器钩子接口
type ServerHook interface {
Name() string
BeforeStart(ctx context.Context) error
AfterStart(ctx context.Context) error
BeforeStop(ctx context.Context) error
AfterStop(ctx context.Context) error
}
// HTTP服务接口
type HTTPService interface {
Name() string
Register(router http.Router) error
HealthCheck(ctx context.Context) error
}
// 创建HTTP服务器启动器
func NewHTTPServerStarter(config *HTTPServerConfig, logger log.Logger) *HTTPServerStarter {
return &HTTPServerStarter{
config: config,
logger: logger,
middleware: make([]http.ServerMiddleware, 0),
routers: make([]http.Router, 0),
services: make([]HTTPService, 0),
hooks: make([]ServerHook, 0),
}
}
// 添加中间件
func (s *HTTPServerStarter) AddMiddleware(middleware ...http.ServerMiddleware) *HTTPServerStarter {
s.mutex.Lock()
defer s.mutex.Unlock()
s.middleware = append(s.middleware, middleware...)
return s
}
// 添加路由
func (s *HTTPServerStarter) AddRouter(router http.Router) *HTTPServerStarter {
s.mutex.Lock()
defer s.mutex.Unlock()
s.routers = append(s.routers, router)
return s
}
// 添加服务
func (s *HTTPServerStarter) AddService(services ...HTTPService) *HTTPServerStarter {
s.mutex.Lock()
defer s.mutex.Unlock()
s.services = append(s.services, services...)
return s
}
// 添加钩子
func (s *HTTPServerStarter) AddHook(hooks ...ServerHook) *HTTPServerStarter {
s.mutex.Lock()
defer s.mutex.Unlock()
s.hooks = append(s.hooks, hooks...)
return s
}
// 启动HTTP服务器
func (s *HTTPServerStarter) Start(ctx context.Context) error {
s.mutex.Lock()
defer s.mutex.Unlock()
if s.started {
return fmt.Errorf("HTTP服务器已经启动")
}
s.logger.Info("开始启动HTTP服务器...")
// 1. 执行启动前钩子
if err := s.executeHooks(ctx, "before_start"); err != nil {
return fmt.Errorf("启动前钩子执行失败: %w", err)
}
// 2. 创建HTTP服务器
server, err := s.createHTTPServer()
if err != nil {
return fmt.Errorf("创建HTTP服务器失败: %w", err)
}
s.server = server
// 3. 检查端口可用性
if err := s.checkPortAvailability(); err != nil {
return fmt.Errorf("端口检查失败: %w", err)
}
// 4. 启动服务器（非阻塞）
go s.runServer(ctx)
s.started = true
// 5. 执行启动后钩子
go func() {
time.Sleep(100 * time.Millisecond) // 等待服务器完全启动
if err := s.executeHooks(ctx, "after_start"); err != nil {
s.logger.Errorf("启动后钩子执行失败: %v", err)
}
}()
s.logger.Infof("HTTP服务器启动成功，监听地址: %s", s.config.Addr)
return nil
}
// 创建HTTP服务器
func (s *HTTPServerStarter) createHTTPServer() (*http.Server, error) {
// 设置默认中间件
defaultMiddleware := []http.ServerMiddleware{
recovery.Recovery(),
logging.Server(s.logger),
metrics.Server(),
tracing.Server(),
s.corsMiddleware(),
s.rateLimitMiddleware(),
s.authMiddleware(),
}
// 合并中间件
allMiddleware := append(defaultMiddleware, s.middleware...)
// 创建服务器实例
srv := http.NewServer(
http.Address(s.config.Addr),
http.Timeout(s.config.Timeout),
http.ReadTimeout(s.config.ReadTimeout),
http.WriteTimeout(s.config.WriteTimeout),
http.IdleTimeout(s.config.IdleTimeout),
http.MaxHeaderBytes(s.config.MaxHeaderBytes),
http.Middleware(allMiddleware...),
http.ResponseEncoder(s.responseEncoder),
http.RequestDecoder(s.requestDecoder),
http.ErrorEncoder(s.errorEncoder),
http.Router(s.routers...),
)
return srv, nil
}
// 检查端口可用性
func (s *HTTPServerStarter) checkPortAvailability() error {
host, port, err := net.SplitHostPort(s.config.Addr)
if err != nil {
return fmt.Errorf("解析监听地址失败: %w", err)
}
// 尝试绑定端口
listener, err := net.Listen("tcp", net.JoinHostPort(host, port))
if err != nil {
return fmt.Errorf("端口 %s 不可用: %w", port, err)
}
listener.Close()
s.logger.Infof("端口 %s 可用", port)
return nil
}
// 运行服务器
func (s *HTTPServerStarter) runServer(ctx context.Context) {
// 注册健康检查端点
s.registerHealthEndpoints()
// 启动服务器
s.logger.Infof("HTTP服务器开始监听: %s", s.config.Addr)
go func() {
<-ctx.Done()
s.logger.Info("收到停止信号，开始关闭HTTP服务器...")
s.shutdown()
}()
if err := s.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
s.logger.Errorf("HTTP服务器运行失败: %v", err)
}
}
// 注册健康检查端点
func (s *HTTPServerStarter) registerHealthEndpoints() {
// 健康检查端点
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
status := s.checkHealth()
if status.IsHealthy {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(status)
})
// 就绪检查端点
http.HandleFunc("/ready", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
status := s.checkReadiness()
if status.IsReady {
w.WriteHeader(http.StatusOK)
} else {
w.WriteHeader(http.StatusServiceUnavailable)
}
json.NewEncoder(w).Encode(status)
})
// 存活检查端点
http.HandleFunc("/live", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(map[string]interface{}{"alive": true})
})
// 服务信息端点
http.HandleFunc("/info", func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
info := s.getServerInfo()
json.NewEncoder(w).Encode(info)
})
}
// 检查健康状态
func (s *HTTPServerStarter) checkHealth() *HealthStatus {
status := &HealthStatus{
IsHealthy: true,
Timestamp: time.Now(),
Services: make(map[string]bool),
}
// 检查所有注册的服务
for _, service := range s.services {
if err := service.HealthCheck(context.Background()); err != nil {
status.IsHealthy = false
status.Services[service.Name()] = false
s.logger.Errorf("服务健康检查失败: service=%s, error=%v", service.Name(), err)
} else {
status.Services[service.Name()] = true
}
}
return status
}
// 检查就绪状态
func (s *HTTPServerStarter) checkReadiness() *ReadinessStatus {
status := &ReadinessStatus{
IsReady: true,
Timestamp: time.Now(),
Checks: make(map[string]bool),
}
// 检查依赖服务
if s.server != nil {
status.Checks["server"] = true
}
// 检查其他依赖项
for _, service := range s.services {
status.Checks[service.Name()] = true
}
return status
}
// 获取服务器信息
func (s *HTTPServerStarter) getServerInfo() *ServerInfo {
return &ServerInfo{
Name: "http-server",
Version: "1.0.0",
StartTime: time.Now(),
Address: s.config.Addr,
Services: s.getServiceNames(),
}
}
// 获取服务名称列表
func (s *HTTPServerStarter) getServiceNames() []string {
names := make([]string, len(s.services))
for i, service := range s.services {
names[i] = service.Name()
}
return names
}
// 执行钩子
func (s *HTTPServerStarter) executeHooks(ctx context.Context, phase string) error {
for _, hook := range s.hooks {
switch phase {
case "before_start":
if err := hook.BeforeStart(ctx); err != nil {
s.logger.Errorf("执行钩子失败: hook=%s, phase=before_start, error=%v", hook.Name(), err)
return err
}
case "after_start":
go func() {
if err := hook.AfterStart(ctx); err != nil {
s.logger.Errorf("执行钩子失败: hook=%s, phase=after_start, error=%v", hook.Name(), err)
}
}()
case "before_stop":
if err := hook.BeforeStop(ctx); err != nil {
s.logger.Errorf("执行钩子失败: hook=%s, phase=before_stop, error=%v", hook.Name(), err)
}
case "after_stop":
go func() {
if err := hook.AfterStop(ctx); err != nil {
s.logger.Errorf("执行钩子失败: hook=%s, phase=after_stop, error=%v", hook.Name(), err)
}
}()
}
}
return nil
}
// 优雅关闭
func (s *HTTPServerStarter) shutdown() {
s.mutex.Lock()
defer s.mutex.Unlock()
if !s.started || s.server == nil {
return
}
s.logger.Info("开始关闭HTTP服务器...")
// 执行关闭前钩子
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
if err := s.executeHooks(ctx, "before_stop"); err != nil {
s.logger.Errorf("关闭前钩子执行失败: %v", err)
}
// 关闭服务器
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := s.server.Shutdown(shutdownCtx); err != nil {
s.logger.Errorf("HTTP服务器关闭失败: %v", err)
} else {
s.logger.Info("HTTP服务器已关闭")
}
s.started = false
// 执行关闭后钩子
go s.executeHooks(context.Background(), "after_stop")
}
// CORS中间件
func (s *HTTPServerStarter) corsMiddleware() http.ServerMiddleware {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Access-Control-Allow-Origin", "*")
w.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
w.Header().Set("Access-Control-Max-Age", "86400")
if r.Method == "OPTIONS" {
w.WriteHeader(http.StatusOK)
return
}
next.ServeHTTP(w, r)
})
}
}
// 限流中间件
func (s *HTTPServerStarter) rateLimitMiddleware() http.ServerMiddleware {
limiter := rate.NewLimiter(1000, 100)
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !limiter.Allow() {
http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
return
}
next.ServeHTTP(w, r)
})
}
}
// 认证中间件
func (s *HTTPServerStarter) authMiddleware() http.ServerMiddleware {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 跳过健康检查等不需要认证的端点
if r.URL.Path == "/health" || r.URL.Path == "/ready" || r.URL.Path == "/live" || r.URL.Path == "/info" {
next.ServeHTTP(w, r)
return
}
// 检查Authorization头
authHeader := r.Header.Get("Authorization")
if authHeader == "" {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
// 验证token
if !s.validateToken(authHeader) {
http.Error(w, "Unauthorized", http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
}
// 验证token
func (s *HTTPServerStarter) validateToken(authHeader string) bool {
// 简单的token验证逻辑
return strings.HasPrefix(authHeader, "Bearer ")
}
// HTTP服务器启动示例
func ExampleHTTPServerStarter() {
logger := log.NewStdLogger(os.Stdout)
config := &HTTPServerConfig{
Addr: ":8080",
Timeout: 30 * time.Second,
ReadTimeout: 15 * time.Second,
WriteTimeout: 15 * time.Second,
IdleTimeout: 60 * time.Second,
MaxHeaderBytes: 1 << 20, // 1MB
}
starter := NewHTTPServerStarter(config, logger)
// 添加服务
userService := NewUserService()
productService := NewProductService()
starter.AddService(userService, productService)
// 添加钩子
starter.AddHook(
NewLoggingHook(logger),
NewMetricsHook(),
)
// 启动服务器
ctx := context.Background()
if err := starter.Start(ctx); err != nil {
logger.Errorf("启动HTTP服务器失败: %v", err)
return
}
// 等待信号
<-ctx.Done()
}
// 钩子实现示例
type LoggingHook struct {
logger log.Logger
}
func (lh *LoggingHook) Name() string {
return "LoggingHook"
}
func (lh *LoggingHook) BeforeStart(ctx context.Context) error {
lh.logger.Info("HTTP服务器启动前日志钩子")
return nil
}
func (lh *LoggingHook) AfterStart(ctx context.Context) error {
lh.logger.Info("HTTP服务器启动后日志钩子")
return nil
}
func (lh *LoggingHook) BeforeStop(ctx context.Context) error {
lh.logger.Info("HTTP服务器停止前日志钩子")
return nil
}
func (lh *LoggingHook) AfterStop(ctx context.Context) error {
lh.logger.Info("HTTP服务器停止后日志钩子")
return nil
}
type MetricsHook struct{}
func (mh *MetricsHook) Name() string {
return "MetricsHook"
}
func (mh *MetricsHook) BeforeStart(ctx context.Context) error {
// 启动指标收集
return nil
}
func (mh *MetricsHook) AfterStart(ctx context.Context) error {
// 记录启动指标
return nil
}
func (mh *MetricsHook) BeforeStop(ctx context.Context) error {
// 停止指标收集
return nil
}
func (mh *MetricsHook) AfterStop(ctx context.Context) error {
// 保存最终指标
return nil
}
// 辅助结构体
type HealthStatus struct {
IsHealthy bool `json:"healthy"`
Timestamp time.Time `json:"timestamp"`
Services map[string]bool `json:"services"`
}
type ReadinessStatus struct {
IsReady bool `json:"ready"`
Timestamp time.Time `json:"timestamp"`
Checks map[string]bool `json:"checks"`
}
type ServerInfo struct {
Name string `json:"name"`
Version string `json:"version"`
StartTime time.Time `json:"start_time"`
Address string `json:"address"`
Services []string `json:"services"`
}
// 服务实现示例
type UserService struct{}
func (us *UserService) Name() string {
return "user-service"
}
func (us *UserService) Register(router http.Router) error {
// 注册用户相关路由
return nil
}
func (us *UserService) HealthCheck(ctx context.Context) error {
// 检查用户服务健康状态
return nil
}
type ProductService struct{}
func (ps *ProductService) Name() string {
return "product-service"
}
func (ps *ProductService) Register(router http.Router) error {
// 注册产品相关路由
return nil
}
func (ps *ProductService) HealthCheck(ctx context.Context) error {
// 检查产品服务健康状态
return nil
}
---
3.6 优雅关闭
01.优雅关闭概述
a.优雅关闭定义
优雅关闭是指应用在接收到停止信号时，能够正确地完成当前正在处理的请求，释放所有占用的资源，然后正常退出的过程。
b.优雅关闭重要性
a.数据完整性
确保正在处理的事务能够完整完成，避免数据不一致。
b.用户体验
避免强制断开连接，提供更好的用户体验。
c.资源清理
及时释放数据库连接、文件句柄等系统资源。
d.监控告警
正确记录关闭过程，便于问题排查和监控。
c.关闭信号处理
a.信号类型
支持SIGINT（Ctrl+C）、SIGTERM（kill命令）等常见停止信号。
b.信号监听
使用signal包监听系统信号，触发关闭流程。
c.超时控制
设置关闭超时时间，防止应用无法正常退出。
02.关闭流程设计
a.关闭阶段
a.停止接受新请求
首先停止接受新的HTTP/gRPC请求。
b.等待现有请求完成
给予正在处理的请求足够时间完成。
c.服务注销
从服务注册中心注销服务实例。
d.资源清理
关闭数据库连接、缓存、文件句柄等资源。
e.进程退出
最后退出应用进程。
b.超时策略
a.分阶段超时
为每个关闭阶段设置独立的超时时间。
b.强制关闭
如果优雅关闭超时，执行强制关闭。
c.进度监控
实时监控关闭进度，记录异常情况。
c.关闭实现
a.代码示例
---
// 优雅关闭实现示例
package graceful
import (
"context"
"fmt"
"log"
"net/http"
"os"
"os/signal"
"sync"
"syscall"
"time"
"github.com/go-kratos/kratos/v2/log"
"google.golang.org/grpc"
)
// 优雅关闭管理器
type GracefulShutdownManager struct {
httpServer *http.Server
grpcServer *grpc.Server
logger log.Logger
shutdownTimeout time.Duration
stopChan chan os.Signal
doneChan chan struct{}
wg sync.WaitGroup
shuttingDown bool
mutex sync.RWMutex
callbacks []ShutdownCallback
metrics *ShutdownMetrics
}
// 关闭回调接口
type ShutdownCallback interface {
Name() string
Priority() int
Execute(ctx context.Context) error
}
// 关闭指标
type ShutdownMetrics struct {
StartTime time.Time
StopTime time.Time
Duration time.Duration
ActiveRequests int64
CompletedRequests int64
FailedRequests int64
CallbacksTotal int
CallbacksSuccess int
CallbacksFailed int
}
// 创建优雅关闭管理器
func NewGracefulShutdownManager(
httpServer *http.Server,
grpcServer *grpc.Server,
logger log.Logger,
shutdownTimeout time.Duration,
) *GracefulShutdownManager {
return &GracefulShutdownManager{
httpServer: httpServer,
grpcServer: grpcServer,
logger: logger,
shutdownTimeout: shutdownTimeout,
stopChan: make(chan os.Signal, 1),
doneChan: make(chan struct{}),
callbacks: make([]ShutdownCallback, 0),
metrics: &ShutdownMetrics{},
}
}
// 添加关闭回调
func (gsm *GracefulShutdownManager) AddCallback(callbacks ...ShutdownCallback) {
gsm.mutex.Lock()
defer gsm.mutex.Unlock()
gsm.callbacks = append(gsm.callbacks, callbacks...)
gsm.logger.Infof("添加关闭回调: %d 个", len(callbacks))
}
// 开始监听停止信号
func (gsm *GracefulShutdownManager) Start() {
gsm.logger.Info("启动优雅关闭监听...")
// 监听停止信号
signal.Notify(gsm.stopChan, syscall.SIGINT, syscall.SIGTERM)
go gsm.handleSignals()
}
// 处理信号
func (gsm *GracefulShutdownManager) handleSignals() {
sig := <-gsm.stopChan
gsm.logger.Infof("收到停止信号: %v", sig)
gsm.startShutdown()
}
// 开始关闭流程
func (gsm *GracefulShutdownManager) startShutdown() {
gsm.mutex.Lock()
if gsm.shuttingDown {
gsm.mutex.Unlock()
return
}
gsm.shuttingDown = true
gsm.mutex.Unlock()
gsm.metrics.StartTime = time.Now()
gsm.logger.Info("开始优雅关闭...")
// 创建关闭上下文
ctx, cancel := context.WithTimeout(context.Background(), gsm.shutdownTimeout)
defer cancel()
// 启动关闭流程
go gsm.executeShutdown(ctx)
// 等待关闭完成
<-gsm.doneChan
}
// 执行关闭流程
func (gsm *GracefulShutdownManager) executeShutdown(ctx context.Context) {
defer close(gsm.doneChan)
// 1. 执行关闭前回调
if err := gsm.executeCallbacks(ctx, "before_shutdown"); err != nil {
gsm.logger.Errorf("关闭前回调执行失败: %v", err)
}
// 2. 停止接受新请求
if err := gsm.stopAcceptingRequests(ctx); err != nil {
gsm.logger.Errorf("停止接受请求失败: %v", err)
}
// 3. 等待现有请求完成
if err := gsm.waitForRequestsCompletion(ctx); err != nil {
gsm.logger.Errorf("等待请求完成失败: %v", err)
}
// 4. 关闭服务器
if err := gsm.shutdownServers(ctx); err != nil {
gsm.logger.Errorf("关闭服务器失败: %v", err)
}
// 5. 执行关闭后回调
if err := gsm.executeCallbacks(ctx, "after_shutdown"); err != nil {
gsm.logger.Errorf("关闭后回调执行失败: %v", err)
}
// 6. 记录关闭指标
gsm.recordShutdownMetrics()
}
// 停止接受新请求
func (gsm *GracefulShutdownManager) stopAcceptingRequests(ctx context.Context) error {
gsm.logger.Info("停止接受新请求...")
if gsm.httpServer != nil {
// HTTP服务器通过Close()方法停止接受新连接
// 注意：这里不能直接关闭，需要等待现有请求完成
}
if gsm.grpcServer != nil {
// gRPC服务器通过GracefulStop()方法优雅关闭
gsm.wg.Add(1)
go func() {
defer gsm.wg.Done()
gsm.grpcServer.GracefulStop()
gsm.logger.Info("gRPC服务器已停止接受新请求")
}()
}
return nil
}
// 等待现有请求完成
func (gsm *GracefulShutdownManager) waitForRequestsCompletion(ctx context.Context) error {
gsm.logger.Info("等待现有请求完成...")
// 设置最大等待时间
maxWaitTime := 30 * time.Second
waitCtx, cancel := context.WithTimeout(ctx, maxWaitTime)
defer cancel()
// 监控活动请求数量
ticker := time.NewTicker(1 * time.Second)
defer ticker.Stop()
for {
select {
case <-waitCtx.Done():
if waitCtx.Err() == context.DeadlineExceeded {
gsm.logger.Warnf("等待请求完成超时，强制关闭")
return fmt.Errorf("等待请求完成超时")
}
return waitCtx.Err()
case <-ticker.C:
activeRequests := gsm.getActiveRequestsCount()
gsm.logger.Infof("活动请求数量: %d", activeRequests)
if activeRequests == 0 {
gsm.logger.Info("所有请求已完成")
return nil
}
gsm.metrics.ActiveRequests = int64(activeRequests)
}
}
}
// 关闭服务器
func (gsm *GracefulShutdownManager) shutdownServers(ctx context.Context) error {
gsm.logger.Info("开始关闭服务器...")
var wg sync.WaitGroup
errors := make(chan error, 2)
// 关闭HTTP服务器
if gsm.httpServer != nil {
wg.Add(1)
go func() {
defer wg.Done()
if err := gsm.shutdownHTTPServer(ctx); err != nil {
errors <- fmt.Errorf("HTTP服务器关闭失败: %w", err)
}
}()
}
// 等待gRPC服务器关闭完成
if gsm.grpcServer != nil {
wg.Add(1)
go func() {
defer wg.Done()
gsm.wg.Wait() // 等待GracefulStop完成
if err := gsm.shutdownGRPCServer(ctx); err != nil {
errors <- fmt.Errorf("gRPC服务器关闭失败: %w", err)
}
}()
}
// 等待所有服务器关闭完成
wg.Wait()
close(errors)
// 收集错误
var shutdownErrors []error
for err := range errors {
if err != nil {
shutdownErrors = append(shutdownErrors, err)
}
}
if len(shutdownErrors) > 0 {
return fmt.Errorf("服务器关闭时发生错误: %v", shutdownErrors)
}
gsm.logger.Info("所有服务器已关闭")
return nil
}
// 关闭HTTP服务器
func (gsm *GracefulShutdownManager) shutdownHTTPServer(ctx context.Context) error {
if gsm.httpServer == nil {
return nil
}
gsm.logger.Info("关闭HTTP服务器...")
shutdownCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
if err := gsm.httpServer.Shutdown(shutdownCtx); err != nil {
gsm.logger.Errorf("HTTP服务器优雅关闭失败，尝试强制关闭: %v", err)
// 强制关闭
if err := gsm.httpServer.Close(); err != nil {
return fmt.Errorf("HTTP服务器强制关闭失败: %w", err)
}
gsm.logger.Warn("HTTP服务器已强制关闭")
} else {
gsm.logger.Info("HTTP服务器已优雅关闭")
}
return nil
}
// 关闭gRPC服务器
func (gsm *GracefulShutdownManager) shutdownGRPCServer(ctx context.Context) error {
if gsm.grpcServer == nil {
return nil
}
gsm.logger.Info("关闭gRPC服务器...")
// gRPC服务器已经通过GracefulStop()停止接受新请求
// 这里只需要等待所有现有RPC调用完成
shutdownCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
done := make(chan struct{})
go func() {
gsm.grpcServer.GracefulStop()
close(done)
}()
select {
case <-done:
gsm.logger.Info("gRPC服务器已优雅关闭")
return nil
case <-shutdownCtx.Done():
gsm.logger.Warnf("gRPC服务器关闭超时，强制停止")
gsm.grpcServer.Stop()
return fmt.Errorf("gRPC服务器关闭超时")
}
}
// 执行关闭回调
func (gsm *GracefulShutdownManager) executeCallbacks(ctx context.Context, phase string) error {
var callbacks []ShutdownCallback
// 根据阶段过滤回调
for _, callback := range gsm.callbacks {
switch phase {
case "before_shutdown":
callbacks = append(callbacks, callback)
case "after_shutdown":
callbacks = append(callbacks, callback)
}
}
// 按优先级排序
for i := 0; i < len(callbacks)-1; i++ {
for j := i + 1; j < len(callbacks); j++ {
if callbacks[i].Priority() > callbacks[j].Priority() {
callbacks[i], callbacks[j] = callbacks[j], callbacks[i]
}
}
}
// 执行回调
for i, callback := range callbacks {
callbackName := callback.Name()
gsm.logger.Infof("执行关闭回调 [%d/%d]: %s", i+1, len(callbacks), callbackName)
callbackCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
if err := callback.Execute(callbackCtx); err != nil {
gsm.logger.Errorf("关闭回调执行失败: name=%s, error=%v", callbackName, err)
gsm.metrics.CallbacksFailed++
} else {
gsm.metrics.CallbacksSuccess++
}
gsm.metrics.CallbacksTotal++
}
return nil
}
// 获取活动请求数量
func (gsm *GracefulShutdownManager) getActiveRequestsCount() int {
// 这里应该从实际的请求计数器获取
// 示例中返回模拟数据
return 0
}
// 记录关闭指标
func (gsm *GracefulShutdownManager) recordShutdownMetrics() {
gsm.metrics.StopTime = time.Now()
gsm.metrics.Duration = gsm.metrics.StopTime.Sub(gsm.metrics.StartTime)
gsm.logger.Infof("优雅关闭完成，耗时: %v", gsm.metrics.Duration)
gsm.logger.Infof("处理请求统计: 完成=%d, 失败=%d",
gsm.metrics.CompletedRequests, gsm.metrics.FailedRequests)
gsm.logger.Infof("回调执行统计: 总数=%d, 成功=%d, 失败=%d",
gsm.metrics.CallbacksTotal, gsm.metrics.CallbacksSuccess, gsm.metrics.CallbacksFailed)
}
// 等待关闭完成
func (gsm *GracefulShutdownManager) Wait() {
<-gsm.doneChan
}
// 优雅关闭管理器使用示例
func ExampleGracefulShutdownManager() {
logger := log.NewStdLogger(os.Stdout)
// 创建HTTP和gRPC服务器
httpServer := &http.Server{
Addr: ":8080",
Handler: nil,
}
grpcServer := grpc.NewServer()
// 创建优雅关闭管理器
shutdownManager := NewGracefulShutdownManager(
httpServer,
grpcServer,
logger,
30*time.Second,
)
// 添加关闭回调
shutdownManager.AddCallback(
&DatabaseCleanupCallback{},
&CacheCleanupCallback{},
&MetricsSaveCallback{},
&NotificationCallback{},
)
// 启动优雅关闭监听
shutdownManager.Start()
// 启动服务器（示例代码）
go func() {
logger.Info("启动服务器...")
time.Sleep(5 * time.Second) // 模拟运行时间
// 模拟接收到停止信号
shutdownManager.stopChan <- syscall.SIGINT
}()
// 等待关闭完成
shutdownManager.Wait()
logger.Info("应用已退出")
}
// 数据库清理回调
type DatabaseCleanupCallback struct{}
func (dcc *DatabaseCleanupCallback) Name() string {
return "DatabaseCleanup"
}
func (dcc *DatabaseCleanupCallback) Priority() int {
return 100 // 最高优先级
}
func (dcc *DatabaseCleanupCallback) Execute(ctx context.Context) error {
log.Println("清理数据库连接...")
// 关闭数据库连接池
return nil
}
// 缓存清理回调
type CacheCleanupCallback struct{}
func (ccc *CacheCleanupCallback) Name() string {
return "CacheCleanup"
}
func (ccc *CacheCleanupCallback) Priority() int {
return 90
}
func (ccc *CacheCleanupCallback) Execute(ctx context.Context) error {
log.Println("清理缓存连接...")
// 关闭Redis连接
return nil
}
// 指标保存回调
type MetricsSaveCallback struct{}
func (msc *MetricsSaveCallback) Name() string {
return "MetricsSave"
}
func (msc *MetricsSaveCallback) Priority() int {
return 50
}
func (msc *MetricsSaveCallback) Execute(ctx context.Context) error {
log.Println("保存运行时指标...")
// 保存性能指标到监控系统
return nil
}
// 通知回调
type NotificationCallback struct{}
func (nc *NotificationCallback) Name() string {
return "Notification"
}
func (nc *NotificationCallback) Priority() int {
return 10 // 最低优先级
}
func (nc *NotificationCallback) Execute(ctx context.Context) error {
log.Println("发送关闭通知...")
// 发送邮件或Slack通知
return nil
}
---
3.7 生命周期管理最佳实践
01.生命周期管理原则
a.设计原则
a.明确性原则
每个生命周期阶段的职责和边界必须明确，避免功能重叠。
b.可靠性原则
确保在任何情况下都能正确执行关闭流程，避免资源泄漏。
c.可观测性原则
提供完整的日志和指标，便于监控和问题排查。
d.灵活性原则
支持通过配置调整生命周期行为，适应不同环境需求。
b.实践准则
a.分层设计
按照应用、服务、资源三个层次组织生命周期管理。
b.异步处理
非关键的初始化和清理操作使用异步方式执行。
c.超时控制
为每个阶段设置合理的超时时间，防止阻塞。
d.错误处理
提供完善的错误处理和恢复机制。
02.应用初始化最佳实践
a.配置管理最佳实践
a.配置分层
支持默认配置、环境配置、命令行参数的分层覆盖机制。
b.配置验证
启动时验证配置的完整性和有效性，及早发现配置错误。
c.配置加密
敏感配置（如数据库密码、API密钥）必须加密存储和传输。
d.配置热更新
支持运行时配置更新，无需重启服务。
b.依赖注入最佳实践
a.接口导向
基于接口设计依赖关系，降低组件间耦合。
b.生命周期管理
明确定义服务的创建、初始化、销毁顺序。
c.循环依赖避免
使用依赖注入容器检测和避免循环依赖。
d.单例与瞬态
合理选择单例和瞬态生命周期，避免资源浪费。
c.初始化最佳实践实现
a.代码示例
---
// 应用初始化最佳实践示例
package bootstrap
import (
"context"
"fmt"
"time"
"github.com/go-kratos/kratos/v2/config"
"github.com/go-kratos/kratos/v2/config/file"
"github.com/go-kratos/kratos/v2/config/env"
"github.com/go-kratos/kratos/v2/log"
"github.com/go-kratos/kratos/v2/middleware/recovery"
"github.com/go-kratos/kratos/v2/middleware/logging"
"github.com/go-kratos/kratos/v2/middleware/metrics"
"github.com/go-kratos/kratos/v2/middleware/tracing"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/transport/grpc"
)
// 应用引导器
type ApplicationBootstrap struct {
config *AppConfig
logger log.Logger
container Container
validator ConfigValidator
stage InitStage
startTime time.Time
metrics *InitMetrics
}
// 初始化阶段
type InitStage string
const (
InitStageConfig InitStage = "config"
InitContainer InitStage = "container"
InitStageDatabase InitStage = "database"
InitStageCache InitStage = "cache"
InitStageServices InitStage = "services"
InitStageServer InitStage = "server"
InitStageComplete InitStage = "complete"
)
// 初始化指标
type InitMetrics struct {
StageDurations map[string]time.Duration
TotalDuration time.Duration
Errors []InitError
Warnings []InitError
}
type InitError struct {
Stage string
Error error
Time time.Time
}
// 创建应用引导器
func NewApplicationBootstrap(logger log.Logger) *ApplicationBootstrap {
return &ApplicationBootstrap{
logger: logger,
validator: NewDefaultConfigValidator(),
stage: InitStageConfig,
metrics: &InitMetrics{
StageDurations: make(map[string]time.Duration),
Errors: make([]InitError, 0),
Warnings: make([]InitError, 0),
},
}
}
// 引导应用启动
func (ab *ApplicationBootstrap) Bootstrap(configPath string) (*App, error) {
ab.startTime = time.Now()
ab.logger.Info("开始应用初始化...")
// 1. 加载配置
if err := ab.loadConfig(configPath); err != nil {
return nil, fmt.Errorf("配置加载失败: %w", err)
}
// 2. 初始化容器
if err := ab.initContainer(); err != nil {
return nil, fmt.Errorf("容器初始化失败: %w", err)
}
// 3. 初始化基础设施
if err := ab.initInfrastructure(); err != nil {
return nil, fmt.Errorf("基础设施初始化失败: %w", err)
}
// 4. 初始化服务
if err := ab.initServices(); err != nil {
return nil, fmt.Errorf("服务初始化失败: %w", err)
}
// 5. 创建应用实例
app, err := ab.createApplication()
if err != nil {
return nil, fmt.Errorf("应用创建失败: %w", err)
}
// 6. 记录初始化结果
ab.logInitializationResult()
ab.stage = InitStageComplete
ab.metrics.TotalDuration = time.Since(ab.startTime)
ab.logger.Infof("应用初始化完成，耗时: %v", ab.metrics.TotalDuration)
return app, nil
}
// 加载配置
func (ab *ApplicationBootstrap) loadConfig(configPath string) error {
ab.stage = InitStageConfig
stageStart := time.Now()
// 创建配置源
sources := []config.Source{
file.NewSource(configPath),
env.NewSource("APP_"),
}
// 创建配置实例
c := config.New(
config.WithSource(sources...),
)
// 加载配置
if err := c.Load(); err != nil {
return ab.recordError(InitStageConfig, err)
}
// 扫描配置
var cfg AppConfig
if err := c.Scan(&cfg); err != nil {
return ab.recordError(InitStageConfig, fmt.Errorf("配置扫描失败: %w", err))
}
// 设置默认值
ab.setConfigDefaults(&cfg)
// 验证配置
if err := ab.validator.Validate(&cfg); err != nil {
return ab.recordError(InitStageConfig, fmt.Errorf("配置验证失败: %w", err))
}
// 加载敏感配置
if err := ab.loadSensitiveConfig(&cfg); err != nil {
return ab.recordWarning(InitStageConfig, fmt.Errorf("敏感配置加载失败: %w", err))
}
ab.config = &cfg
ab.metrics.StageDurations[string(InitStageConfig)] = time.Since(stageStart)
ab.logger.Infof("配置加载完成: %+v", ab.getConfigSummary())
return nil
}
// 初始化容器
func (ab *ApplicationBootstrap) initContainer() error {
ab.stage = InitContainer
stageStart := time.Now()
// 创建依赖注入容器
ab.container = NewContainer()
// 注册基础服务
if err := ab.registerBaseServices(); err != nil {
return ab.recordError(InitContainer, err)
}
// 验证容器
if err := ab.validateContainer(); err != nil {
return ab.recordError(InitContainer, err)
}
ab.metrics.StageDurations[string(InitContainer)] = time.Since(stageStart)
ab.logger.Info("依赖注入容器初始化完成")
return nil
}
// 初始化基础设施
func (ab *ApplicationBootstrap) initInfrastructure() error {
stages := []struct {
name string
init func() error
}{
{"database", ab.initDatabase},
{"cache", ab.initCache},
{"message_queue", ab.initMessageQueue},
{"monitoring", ab.initMonitoring},
}
for _, stage := range stages {
stageStart := time.Now()
if err := stage.init(); err != nil {
return ab.recordError(InitStageDatabase, fmt.Errorf("%s初始化失败: %w", stage.name, err))
}
ab.metrics.StageDurations[stage.name] = time.Since(stageStart)
ab.logger.Infof("%s初始化完成", stage.name)
}
return nil
}
// 初始化数据库
func (ab *ApplicationBootstrap) initDatabase() error {
dbConfig := ab.config.Data.Database
// 创建数据库服务
dbService := NewDatabaseService(dbConfig, ab.logger)
if err := ab.container.RegisterSingleton("database", func(c Container) (interface{}, error) {
return dbService, nil
}); err != nil {
return err
}
// 测试数据库连接
if err := dbService.Ping(context.Background()); err != nil {
return fmt.Errorf("数据库连接测试失败: %w", err)
}
// 执行数据库迁移
if err := dbService.Migrate(context.Background()); err != nil {
ab.logger.Warnf("数据库迁移失败: %v", err)
}
return nil
}
// 初始化缓存
func (ab *ApplicationBootstrap) initCache() error {
cacheConfig := ab.config.Data.Redis
// 创建缓存服务
cacheService := NewCacheService(cacheConfig, ab.logger)
if err := ab.container.RegisterSingleton("cache", func(c Container) (interface{}, error) {
return cacheService, nil
}); err != nil {
return err
}
// 测试缓存连接
if err := cacheService.Ping(context.Background()); err != nil {
return fmt.Errorf("缓存连接测试失败: %w", err)
}
// 预热缓存
if err := ab.warmupCache(cacheService); err != nil {
ab.logger.Warnf("缓存预热失败: %v", err)
}
return nil
}
// 初始化消息队列
func (ab *ApplicationBootstrap) initMessageQueue() error {
mqConfig := ab.config.MessageQueue
// 创建消息队列服务
mqService := NewMessageQueueService(mqConfig, ab.logger)
if err := ab.container.RegisterSingleton("message_queue", func(c Container) (interface{}, error) {
return mqService, nil
}); err != nil {
return err
}
// 声明队列
if err := mqService.DeclareQueues(context.Background()); err != nil {
return fmt.Errorf("消息队列声明失败: %w", err)
}
return nil
}
// 初始化监控
func (ab *ApplicationBootstrap) initMonitoring() error {
// 创建监控服务
monitoringService := NewMonitoringService(ab.logger)
if err := ab.container.RegisterSingleton("monitoring", func(c Container) (interface{}, error) {
return monitoringService, nil
}); err != nil {
return err
}
// 启动指标收集
if err := monitoringService.StartMetricsCollection(context.Background()); err != nil {
ab.logger.Warnf("指标收集启动失败: %v", err)
}
return nil
}
// 初始化服务
func (ab *ApplicationBootstrap) initServices() error {
// 注册业务服务
services := []struct {
name string
factory func() (interface{}, error)
}{
{"user_repository", ab.createUserRepository},
{"product_repository", ab.createProductRepository},
{"order_repository", ab.createOrderRepository},
{"user_service", ab.createUserService},
{"product_service", ab.createProductService},
{"order_service", ab.createOrderService},
}
for _, service := range services {
if err := ab.container.Register(service.name, service.factory); err != nil {
return fmt.Errorf("注册服务失败: name=%s, error=%w", service.name, err)
}
}
ab.logger.Infof("业务服务注册完成，共 %d 个", len(services))
return nil
}
// 创建应用实例
func (ab *ApplicationBootstrap) createApplication() (*App, error) {
// 解析服务器组件
httpServer, err := ab.container.Resolve("http_server")
if err != nil {
return nil, fmt.Errorf("解析HTTP服务器失败: %w", err)
}
grpcServer, err := ab.container.Resolve("grpc_server")
if err != nil {
return nil, fmt.Errorf("解析gRPC服务器失败: %w", err)
}
// 解析注册中心
registrar, err := ab.container.Resolve("registrar")
if err != nil {
return nil, fmt.Errorf("解析注册中心失败: %w", err)
}
// 创建应用
app := &App{
id: ab.config.ID,
name: ab.config.Name,
version: ab.config.Version,
metadata: ab.config.Metadata,
servers: []Server{httpServer.(Server), grpcServer.(Server)},
registrar: registrar.(Registrar),
logger: ab.logger,
}
// 添加生命周期钩子
ab.addLifecycleHooks(app)
return app, nil
}
// 添加生命周期钩子
func (ab *ApplicationBootstrap) addLifecycleHooks(app *App) {
// 启动前钩子
app.BeforeStart(ab.createBeforeStartHooks(app)...)
// 启动后钩子
app.AfterStart(ab.createAfterStartHooks(app)...)
// 停止前钩子
app.BeforeStop(ab.createBeforeStopHooks(app)...)
// 停止后钩子
app.AfterStop(ab.createAfterStopHooks(app)...)
}
// 创建启动前钩子
func (ab *ApplicationBootstrap) createBeforeStartHooks(app *App) []HookFunc {
return []HookFunc{
func(ctx context.Context) error {
ab.logger.Info("执行启动前钩子...")
return nil
},
}
}
// 创建启动后钩子
func (ab *ApplicationBootstrap) createAfterStartHooks(app *App) []HookFunc {
return []HookFunc{
func(ctx context.Context) error {
ab.logger.Info("执行启动后钩子...")
return nil
},
}
}
// 创建停止前钩子
func (ab *ApplicationBootstrap) createBeforeStopHooks(app *App) []HookFunc {
return []HookFunc{
func(ctx context.Context) error {
ab.logger.Info("执行停止前钩子...")
return nil
},
}
}
// 创建停止后钩子
func (ab *ApplicationBootstrap) createAfterStopHooks(app *App) []HookFunc {
return []HookFunc{
func(ctx context.Context) error {
ab.logger.Info("执行停止后钩子...")
return nil
},
}
}
// 辅助方法
func (ab *ApplicationBootstrap) recordError(stage InitStage, err error) error {
ab.metrics.Errors = append(ab.metrics.Errors, InitError{
Stage: string(stage),
Error: err,
Time: time.Now(),
})
return err
}
func (ab *ApplicationBootstrap) recordWarning(stage InitStage, err error) error {
ab.metrics.Warnings = append(ab.metrics.Warnings, InitError{
Stage: string(stage),
Error: err,
Time: time.Now(),
})
return nil
}
func (ab *ApplicationBootstrap) setConfigDefaults(config *AppConfig) {
if config.ID == "" {
config.ID = "kratos-service"
}
if config.Name == "" {
config.Name = "Kratos Service"
}
if config.Version == "" {
config.Version = "1.0.0"
}
if config.Env == "" {
config.Env = "development"
}
}
func (ab *ApplicationBootstrap) loadSensitiveConfig(config *AppConfig) error {
// 从环境变量或密钥管理系统加载敏感配置
if config.Data.Database.Password == "" {
config.Data.Database.Password = os.Getenv("DB_PASSWORD")
}
if config.Data.Redis.Password == "" {
config.Data.Redis.Password = os.Getenv("REDIS_PASSWORD")
}
if config.Auth.JWTSecret == "" {
config.Auth.JWTSecret = os.Getenv("JWT_SECRET")
}
return nil
}
func (ab *ApplicationBootstrap) registerBaseServices() error {
// 注册配置服务
if err := ab.container.RegisterSingleton("config", func(c Container) (interface{}, error) {
return ab.config, nil
}); err != nil {
return err
}
// 注册日志服务
if err := ab.container.RegisterSingleton("logger", func(c Container) (interface{}, error) {
return ab.logger, nil
}); err != nil {
return err
}
// 注册HTTP服务器
if err := ab.container.RegisterSingleton("http_server", func(c Container) (interface{}, error) {
return ab.createHTTPServer(), nil
}); err != nil {
return err
}
// 注册gRPC服务器
if err := ab.container.RegisterSingleton("grpc_server", func(c Container) (interface{}, error) {
return ab.createGRPCServer(), nil
}); err != nil {
return err
}
// 注册注册中心
if err := ab.container.RegisterSingleton("registrar", func(c Container) (interface{}, error) {
return ab.createRegistrar(), nil
}); err != nil {
return err
}
return nil
}
func (ab *ApplicationBootstrap) createHTTPServer() (interface{}, error) {
// 创建HTTP服务器实例
return http.NewServer(
http.Address(ab.config.Server.HTTP.Addr),
http.Timeout(ab.config.Server.HTTP.Timeout),
http.Middleware(
recovery.Recovery(),
logging.Server(ab.logger),
metrics.Server(),
tracing.Server(),
),
)
}
func (ab *ApplicationBootstrap) createGRPCServer() (interface{}, error) {
// 创建gRPC服务器实例
return grpc.NewServer(
grpc.Address(ab.config.Server.GRPC.Addr),
grpc.Timeout(ab.config.Server.GRPC.Timeout),
grpc.Middleware(
recovery.Recovery(),
logging.Server(ab.logger),
metrics.Server(),
tracing.Server(),
),
)
}
func (ab *ApplicationBootstrap) createRegistrar() (interface{}, error) {
// 创建服务注册中心实例
return NewRegistryService(ab.config.Registry, ab.logger)
}
func (ab *ApplicationBootstrap) validateContainer() error {
// 检查关键服务
criticalServices := []string{
"logger",
"config",
"http_server",
"grpc_server",
}
for _, service := range criticalServices {
if _, err := ab.container.Resolve(service); err != nil {
return fmt.Errorf("关键服务未注册: %s", service)
}
}
return nil
}
func (ab *ApplicationBootstrap) warmupCache(cache CacheService) error {
// 预热热点数据
hotKeys := []string{
"config:system",
"user:permissions",
"product:categories",
}
for _, key := range hotKeys {
if err := cache.Set(key, "dummy_value", 5*time.Minute); err != nil {
ab.logger.Warnf("缓存预热失败: key=%s, error=%v", key, err)
}
}
return nil
}
func (ab *ApplicationBootstrap) createUserRepository() (interface{}, error) {
database, err := ab.container.Resolve("database")
if err != nil {
return nil, err
}
cache, err := ab.container.Resolve("cache")
if err != nil {
return nil, err
}
return NewUserRepository(database.(DatabaseService), cache.(CacheService), ab.logger), nil
}
func (ab *ApplicationBootstrap) createProductRepository() (interface{}, error) {
database, err := ab.container.Resolve("database")
if err != nil {
return nil, err
}
cache, err := ab.container.Resolve("cache")
if err != nil {
return nil, err
}
return NewProductRepository(database.(DatabaseService), cache.(CacheService), ab.logger), nil
}
func (ab *ApplicationBootstrap) createOrderRepository() (interface{}, error) {
database, err := ab.container.Resolve("database")
if err != nil {
return nil, err
}
cache, err := ab.container.Resolve("cache")
if err != nil {
return nil, err
}
return NewOrderRepository(database.(DatabaseService), cache.(CacheService), ab.logger), nil
}
func (ab *ApplicationBootstrap) createUserService() (interface{}, error) {
userRepo, err := ab.container.Resolve("user_repository")
if err != nil {
return nil, err
}
logger, err := ab.container.Resolve("logger")
if err != nil {
return nil, err
}
return NewUserService(userRepo.(UserRepository), logger.(log.Logger)), nil
}
func (ab *ApplicationBootstrap) createProductService() (interface{}, error) {
productRepo, err := ab.container.Resolve("product_repository")
if err != nil {
return nil, err
}
logger, err := ab.container.Resolve("logger")
if err != nil {
return nil, err
}
return NewProductService(productRepo.(ProductRepository), logger.(log.Logger)), nil
}
func (ab *ApplicationBootstrap) createOrderService() (interface{}, error) {
orderRepo, err := ab.container.Resolve("order_repository")
if err != nil {
return nil, err
}
logger, err := ab.container.Resolve("logger")
if err != nil {
return nil, err
}
return NewOrderService(orderRepo.(OrderRepository), logger.(log.Logger)), nil
}
func (ab *ApplicationBootstrap) getConfigSummary() map[string]interface{} {
return map[string]interface{}{
"name": ab.config.Name,
"version": ab.config.Version,
"env": ab.config.Env,
"debug": ab.config.Debug,
"servers": []string{
ab.config.Server.HTTP.Addr,
ab.config.Server.GRPC.Addr,
},
}
}
func (ab *ApplicationBootstrap) logInitializationResult() {
ab.logger.Info("初始化结果:")
ab.logger.Infof(" 总耗时: %v", ab.metrics.TotalDuration)
for stage, duration := range ab.metrics.StageDurations {
ab.logger.Infof(" %s: %v", stage, duration)
}
if len(ab.metrics.Errors) > 0 {
ab.logger.Errorf(" 错误数量: %d", len(ab.metrics.Errors))
for i, err := range ab.metrics.Errors {
ab.logger.Errorf(" [%d] %s: %v (时间: %s)", i+1, err.Stage, err.Error, err.Time.Format("15:04:05"))
}
}
if len(ab.metrics.Warnings) > 0 {
ab.logger.Warnf(" 警告数量: %d", len(ab.metrics.Warnings))
for i, warning := range ab.metrics.Warnings {
ab.logger.Warnf(" [%d] %s: %v (时间: %s)", i+1, warning.Stage, warning.Error, warning.Time.Format("15:04:05"))
}
}
}
// 应用初始化最佳实践示例
func ExampleApplicationBootstrap() {
logger := log.NewStdLogger(os.Stdout)
bootstrap := NewApplicationBootstrap(logger)
app, err := bootstrap.Bootstrap("configs/config.yaml")
if err != nil {
logger.Fatalf("应用初始化失败: %v", err)
}
// 启动应用
ctx := context.Background()
if err := app.Run(ctx); err != nil {
logger.Errorf("应用运行失败: %v", err)
}
logger.Info("应用已退出")
}
---
4 API 接口设计
4.1 汇总：3种接口类型
01.Kratos接口类型概览
a.gRPC接口
a.定义方式
使用Protocol Buffers定义服务接口和数据模型，支持强类型检查。
b.调用模式
支持一元调用、客户端流式、服务端流式和双向流式四种RPC调用模式。
c.性能特点
基于HTTP/2协议，支持多路复用、头部压缩，性能优异。
d.适用场景
适用于内部微服务间的高性能通信。
b.HTTP接口
a.协议支持
支持RESTful风格的HTTP接口，兼容JSON、XML等多种数据格式。
b.方法支持
支持GET、POST、PUT、DELETE等标准HTTP方法。
c.中间件集成
与Kratos中间件系统深度集成，支持认证、授权、限流等。
d.适用场景
适用于Web应用、移动应用等客户端接入场景。
c.统一接口设计
a.接口抽象
通过接口抽象，实现HTTP和gRPC的统一处理。
b.代码复用
业务逻辑与传输协议解耦，支持代码复用。
c.协议转换
支持HTTP到gRPC的协议转换和代理。
d.适用场景
适用于需要同时支持多种协议的复杂应用。
02.接口设计最佳实践
a.统一建模
a.数据模型统一
使用Protocol Buffers定义统一的数据模型，确保不同协议间的一致性。
b.业务逻辑统一
业务逻辑与传输层解耦，支持多协议共享。
c.错误处理统一
统一的错误码和错误消息格式，提供一致的错误处理体验。
b.版本管理
a.API版本控制
通过路径、参数、头信息等方式进行API版本管理。
b.向后兼容
保证新版本API的向后兼容性，支持平滑升级。
c.废弃策略
制定API废弃策略，提供充足的迁移时间。
c.接口文档化
a.自动生成
基于Protocol Buffers定义自动生成API文档。
b.示例代码
提供完整的客户端调用示例代码。
c.交互式文档
集成Swagger/OpenAPI等交互式文档工具。
03.接口类型对比分析
a.性能对比
a.数据序列化
gRPC使用Protocol Buffers二进制序列化，比HTTP的JSON序列化性能更优。
b.网络传输
gRPC基于HTTP/2，支持多路复用；HTTP基于HTTP/1.1，连接开销较大。
c.压缩效率
gRPC内置压缩支持，HTTP需要额外配置。
b.开发效率对比
a.工具链成熟度
HTTP生态成熟，工具丰富；gRPC工具链相对较新。
b.调试便利性
HTTP易于调试（cURL、浏览器）；gRPC需要专用工具。
c.社区支持
HTTP社区更广泛，gRPC在微服务领域快速成长。
c.适用场景分析
a.内部服务通信
推荐使用gRPC，性能优异，类型安全。
b.外部API接口
推荐使用HTTP，生态成熟，易于集成。
c.移动端接入
推荐使用HTTP，网络友好，兼容性好。
04.接口架构设计示例
---
// Kratos接口架构设计示例
package api
import (
"context"
"fmt"
"net/http"
"github.com/go-kratos/kratos/v2/transport/grpc"
"github.com/go-kratos/kratos/v2/transport/http"
)
// 统一接口定义
type UserService interface {
CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error)
GetUser(ctx context.Context, req *GetUserRequest) (*GetUserResponse, error)
UpdateUser(ctx context.Context, req *UpdateUserRequest) (*UpdateUserResponse, error)
DeleteUser(ctx context.Context, req *DeleteUserRequest) (*DeleteUserResponse, error)
ListUsers(ctx context.Context, req *ListUsersRequest) (*ListUsersResponse, error)
}
// 用户服务实现
type userService struct {
userRepo UserRepository
authSrv AuthService
logger Logger
}
func NewUserService(userRepo UserRepository, authSrv AuthService, logger Logger) UserService {
return &userService{
userRepo: userRepo,
authSrv: authSrv,
logger: logger,
}
}
// HTTP接口处理器
type UserHTTPHandler struct {
svc UserService
}
func NewUserHTTPHandler(svc UserService) *UserHTTPHandler {
return &UserHTTPHandler{
svc: svc,
}
}
// HTTP路由注册
func (h *UserHTTPHandler) RegisterRoutes(router *http.Router) {
router.POST("/users", h.CreateUser)
router.GET("/users/{id}", h.GetUser)
router.PUT("/users/{id}", h.UpdateUser)
router.DELETE("/users/{id}", h.DeleteUser)
router.GET("/users", h.ListUsers)
}
// HTTP接口实现
func (h *UserHTTPHandler) CreateUser(ctx context.Context, req interface{}) (interface{}, error) {
httpReq := req.(*http.Request)
var createUserReq CreateUserRequest
if err := json.NewDecoder(httpReq.Body).Decode(&createUserReq); err != nil {
return nil, fmt.Errorf("解析请求体失败: %w", err)
}
return h.svc.CreateUser(ctx, &createUserReq)
}
func (h *UserHTTPHandler) GetUser(ctx context.Context, req interface{}) (interface{}, error) {
httpReq := req.(*http.Request)
userID := httpReq.URL.Query().Get("id")
if userID == "" {
return nil, fmt.Errorf("缺少用户ID参数")
}
getUserReq := &GetUserRequest{
UserId: userID,
}
return h.svc.GetUser(ctx, getUserReq)
}
// gRPC接口实现
type UserGRPCServer struct {
pb.UnimplementedUserServiceServer
svc UserService
}
func NewUserGRPCServer(svc UserService) *UserGRPCServer {
return &UserGRPCServer{
svc: svc,
}
}
func (s *UserGRPCServer) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.CreateUserResponse, error) {
createUserReq := &CreateUserRequest{
Username: req.Username,
Email: req.Email,
FullName: req.FullName,
Password: req.Password,
}
resp, err := s.svc.CreateUser(ctx, createUserReq)
if err != nil {
return nil, err
}
return &pb.CreateUserResponse{
User: &pb.User{
Id: resp.User.Id,
Username: resp.User.Username,
Email: resp.User.Email,
FullName: resp.User.FullName,
Status: resp.User.Status,
CreatedAt: timestamppb.New(resp.User.CreatedAt),
},
}, nil
}
func (s *UserGRPCServer) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.GetUserResponse, error) {
getUserReq := &GetUserRequest{
UserId: req.UserId,
}
resp, err := s.svc.GetUser(ctx, getUserReq)
if err != nil {
return nil, err
}
return &pb.GetUserResponse{
User: &pb.User{
Id: resp.User.Id,
Username: resp.User.Username,
Email: resp.User.Email,
FullName: resp.User.FullName,
Status: resp.User.Status,
CreatedAt: timestamppb.New(resp.User.CreatedAt),
UpdatedAt: timestamppb.New(resp.User.UpdatedAt),
},
}, nil
}
// 业务逻辑实现
func (s *userService) CreateUser(ctx context.Context, req *CreateUserRequest) (*CreateUserResponse, error) {
s.logger.Infof("创建用户请求: username=%s, email=%s", req.Username, req.Email)
// 参数验证
if err := s.validateCreateUserRequest(req); err != nil {
return nil, fmt.Errorf("参数验证失败: %w", err)
}
// 检查用户是否已存在
if exists, err := s.userRepo.ExistsByEmail(ctx, req.Email); err != nil {
return nil, fmt.Errorf("检查用户是否存在失败: %w", err)
} else if exists {
return nil, fmt.Errorf("用户已存在: %s", req.Email)
}
// 创建用户实体
user := &User{
Username: req.Username,
Email: req.Email,
FullName: req.FullName,
Status: UserStatusActive,
CreatedAt: time.Now(),
UpdatedAt: time.Now(),
}
// 密码加密
if req.Password != "" {
hashedPassword, err := s.hashPassword(req.Password)
if err != nil {
return nil, fmt.Errorf("密码加密失败: %w", err)
}
user.Password = hashedPassword
}
// 保存用户
if err := s.userRepo.Create(ctx, user); err != nil {
return nil, fmt.Errorf("创建用户失败: %w", err)
}
s.logger.Infof("用户创建成功: id=%s, username=%s", user.Id, user.Username)
return &CreateUserResponse{
User: user,
}, nil
}
func (s *userService) GetUser(ctx context.Context, req *GetUserRequest) (*GetUserResponse, error) {
s.logger.Infof("获取用户请求: id=%s", req.UserId)
if req.UserId == "" {
return nil, fmt.Errorf("用户ID不能为空")
}
// 从数据库获取用户
user, err := s.userRepo.GetByID(ctx, req.UserId)
if err != nil {
if err == ErrUserNotFound {
return nil, fmt.Errorf("用户不存在: %s", req.UserId)
}
return nil, fmt.Errorf("获取用户失败: %w", err)
}
s.logger.Infof("用户获取成功: id=%s, username=%s", user.Id, user.Username)
return &GetUserResponse{
User: user,
}, nil
}
// 数据模型定义
type User struct {
Id string `json:"id"`
Username string `json:"username"`
Email string `json:"email"`
FullName string `json:"full_name"`
Password string `json:"-"` // 不序列化密码
Status string `json:"status"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
type CreateUserRequest struct {
Username string `json:"username" validate:"required,min=3,max=20"`
Email string `json:"email" validate:"required,email"`
FullName string `json:"full_name" validate:"required,min=1,max=100"`
Password string `json:"password" validate:"required,min=8"`
}
type CreateUserResponse struct {
User *User `json:"user"`
}
type GetUserRequest struct {
UserId string `json:"user_id" validate:"required"`
}
type GetUserResponse struct {
User *User `json:"user"`
}
type UpdateUserRequest struct {
UserId string `json:"user_id" validate:"required"`
Email string `json:"email,omitempty" validate:"omitempty,email"`
FullName string `json:"full_name,omitempty" validate:"omitempty,min=1,max=100"`
}
type UpdateUserResponse struct {
User *User `json:"user"`
}
type DeleteUserRequest struct {
UserId string `json:"user_id" validate:"required"`
}
type DeleteUserResponse struct {
Success bool `json:"success"`
}
type ListUsersRequest struct {
Page int `json:"page" validate:"required,min=1"`
PageSize int `json:"page_size" validate:"required,min=1,max=100"`
Filter string `json:"filter,omitempty"`
}
type ListUsersResponse struct {
Users []*User `json:"users"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int `json:"total_pages"`
}
// 错误定义
var (
ErrUserNotFound = errors.New("用户不存在")
ErrInvalidInput = errors.New("无效的输入参数")
)
// 接口定义
type UserRepository interface {
Create(ctx context.Context, user *User) error
GetByID(ctx context.Context, id string) (*User, error)
ExistsByEmail(ctx context.Context, email string) (bool, error)
Update(ctx context.Context, user *User) error
Delete(ctx context.Context, id string) error
List(ctx context.Context, filter string, page, pageSize int) ([]*User, int64, error)
}
type AuthService interface {
GenerateToken(user *User) (string, error)
ValidateToken(token string) (*User, error)
}
type Logger interface {
Infof(format string, args ...interface{})
Errorf(format string, args ...interface{})
Warnf(format string, args ...interface{})
Debugf(format string, args ...interface{})
}
// 业务方法实现
func (s *userService) validateCreateUserRequest(req *CreateUserRequest) error {
if req.Username == "" {
return fmt.Errorf("用户名不能为空")
}
if len(req.Username) < 3 || len(req.Username) > 20 {
return fmt.Errorf("用户名长度必须在3-20个字符之间")
}
if req.Email == "" {
return fmt.Errorf("邮箱不能为空")
}
if !isValidEmail(req.Email) {
return fmt.Errorf("邮箱格式不正确")
}
if req.FullName == "" {
return fmt.Errorf("全名不能为空")
}
return nil
}
func (s *userService) hashPassword(password string) (string, error) {
// 使用bcrypt进行密码加密
hashedBytes, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
if err != nil {
return "", err
}
return string(hashedBytes), nil
}
func isValidEmail(email string) bool {
emailRegex := regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
return emailRegex.MatchString(email)
}
// 接口注册和使用示例
func ExampleAPIRegistration() {
// 创建依赖
userRepo := NewUserRepository()
authSrv := NewAuthService()
logger := NewLogger()
// 创建用户服务
userService := NewUserService(userRepo, authSrv, logger)
// 创建HTTP处理器
httpHandler := NewUserHTTPHandler(userService)
// 创建gRPC服务器
grpcServer := grpc.NewServer()
pb.RegisterUserServiceServer(grpcServer, NewUserGRPCServer(userService))
// 注册HTTP路由
httpRouter := http.NewRouter()
httpHandler.RegisterRoutes(httpRouter)
// 启动服务器
httpServer := http.NewServer(
http.Address(":8080"),
http.Handler(httpRouter),
)
grpcServerAddr := ":9090"
log.Printf("HTTP服务器启动在: %s", ":8080")
log.Printf("gRPC服务器启动在: %s", grpcServerAddr)
// 这里应该启动HTTP和gRPC服务器
// httpServer.Start(ctx)
// grpcServer.Start(grpcServerAddr)
}
// 辅助函数和类型定义
func NewUserRepository() UserRepository {
// 返回用户仓储实例
return nil
}
func NewAuthService() AuthService {
// 返回认证服务实例
return nil
}
func NewLogger() Logger {
// 返回日志记录器实例
return nil
}
// 用户状态常量
const (
UserStatusActive = "active"
UserStatusInactive = "inactive"
UserStatusSuspended = "suspended"
)
// Protobuf定义引用（假设生成的pb包）
package pb
// 这里应该包含自动生成的protobuf定义
type UserServiceServer interface {
CreateUser(context.Context, *CreateUserRequest) (*CreateUserResponse, error)
GetUser(context.Context, *GetUserRequest) (*GetUserResponse, error)
// ... 其他方法
}
type UnimplementedUserServiceServer struct {
}
type CreateUserRequest struct {
Username string `protobuf:"bytes,1,opt,name=username,proto3" json:"username,omitempty"`
Email string `protobuf:"bytes,2,opt,name=email,proto3" json:"email,omitempty"`
FullName string `protobuf:"bytes,3,opt,name=full_name,json=fullName,proto3" json:"full_name,omitempty"`
Password string `protobuf:"bytes,4,opt,name=password,proto3" json:"password,omitempty"`
}
type CreateUserResponse struct {
User *User `protobuf:"bytes,1,opt,name=user,proto3" json:"user,omitempty"`
}
type User struct {
Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
Username string `protobuf:"bytes,2,opt,name=username,proto3" json:"username,omitempty"`
Email string `protobuf:"bytes,3,opt,name=email,proto3" json:"email,omitempty"`
FullName string `protobuf:"bytes,4,opt,name=full_name,json=fullName,proto3" json:"full_name,omitempty"`
Status string `protobuf:"bytes,5,opt,name=status,proto3" json:"status,omitempty"`
CreatedAt *timestamppb.Timestamp `protobuf:"bytes,6,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
UpdatedAt *timestamppb.Timestamp `protobuf:"bytes,7,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
}
func RegisterUserServiceServer(s grpc.ServiceRegistrar, srv UserServiceServer) {
// 注册服务的实现
}
// 依赖包导入
import (
"github.com/golang/protobuf/ptypes/timestamppb"
"github.com/go-kratos/kratos/v2/transport/http"
"github.com/go-kratos/kratos/v2/transport/grpc"
"golang.org/x/crypto/bcrypt"
"google.golang.org/grpc"
"google.golang.org/protobuf/encoding/protojson"
)
---
4.2 gRPC 接口定义
01.gRPC基础概念
a.Protocol Buffers
a.定义方式
使用.proto文件定义服务接口和数据模型，支持强类型检查。
b.数据序列化
二进制序列化格式，性能优异，支持向前向后兼容。
c.代码生成
自动生成多语言的客户端和服务端代码。
d.版本管理
通过字段编号实现版本兼容性，支持字段添加和删除。
b.gRPC调用模式
a.一元调用(Unary)
客户端发送一个请求，服务器返回一个响应。
b.客户端流式(Client Streaming)
客户端发送消息流，服务器返回一个响应。
c.服务端流式(Server Streaming)
客户端发送一个请求，服务器返回消息流。
d.双向流式(Bidirectional Streaming)
客户端和服务器都可以独立发送消息流。
c.gRPC优势特性
a.性能优势
基于HTTP/2协议，支持多路复用、头部压缩、二进制传输。
b.类型安全
强类型接口定义，编译时类型检查。
c.跨语言支持
支持多种编程语言，便于异构系统集成。
d.流式处理
原生支持流式数据处理，适合大数据传输场景。
02.gRPC服务定义示例
a.基础服务定义
a.用户服务定义
定义用户相关的CRUD操作接口。
b.数据模型定义
定义用户、角色、权限等数据模型。
c.错误处理定义
定义标准化的错误码和错误消息。
d.完整Protobuf示例
---
// 用户服务protobuf定义示例
// user.proto
syntax = "proto3";
package user.v1;
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/api/annotations.proto";
import "validate/validate.proto";
// 用户服务定义
service UserService {
// 创建用户
rpc CreateUser(CreateUserRequest) returns (CreateUserResponse) {
option (google.api.http) = {
post: "/v1/users"
body: "*"
};
}
// 获取用户信息
rpc GetUser(GetUserRequest) returns (GetUserResponse) {
option (google.api.http) = {
get: "/v1/users/{user_id}"
};
}
// 更新用户信息
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse) {
option (google.api.http) = {
put: "/v1/users/{user_id}"
body: "*"
};
}
// 删除用户
rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse) {
option (google.api.http) = {
delete: "/v1/users/{user_id}"
};
}
// 列出用户（分页）
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
option (google.api.http) = {
get: "/v1/users"
};
}
// 批量创建用户（流式）
rpc BatchCreateUsers(stream BatchCreateUsersRequest) returns (BatchCreateUsersResponse) {
option (google.api.http) = {
post: "/v1/users/batch"
body: "*"
};
}
// 流式查询用户
rpc StreamUsers(StreamUsersRequest) returns (stream User) {
option (google.api.http) = {
get: "/v1/users/stream"
};
}
// 搜索用户
rpc SearchUsers(SearchUsersRequest) returns (SearchUsersResponse) {
option (google.api.http) = {
post: "/v1/users/search"
body: "*"
};
}
// 更新用户状态
rpc UpdateUserStatus(UpdateUserStatusRequest) returns (UpdateUserStatusResponse) {
option (google.api.http) = {
patch: "/v1/users/{user_id}/status"
body: "*"
};
}
}
// 用户角色枚举
enum UserRole {
USER_ROLE_UNSPECIFIED = 0;
USER_ROLE_ADMIN = 1;
USER_ROLE_USER = 2;
USER_ROLE_MODERATOR = 3;
USER_ROLE_GUEST = 4;
}
// 用户状态枚举
enum UserStatus {
USER_STATUS_UNSPECIFIED = 0;
USER_STATUS_ACTIVE = 1;
USER_STATUS_INACTIVE = 2;
USER_STATUS_SUSPENDED = 3;
USER_STATUS_DELETED = 4;
}
// 用户信息消息
message User {
string user_id = 1 [(validate.rules).string.uuid = true];
string username = 2 [(validate.rules).string = {min_len: 3, max_len: 20, pattern: "^[a-zA-Z0-9_]+$"}];
string email = 3 [(validate.rules).string.email = true];
string full_name = 4 [(validate.rules).string = {min_len: 1, max_len: 100}];
string phone = 5 [(validate.rules).string.pattern = "^1[3-9]\\d{9}$"];
string avatar = 6 [(validate.rules).string.uri = true];
UserRole role = 7 [(validate.rules).enum = {in: [1, 2, 3, 4]}];
UserStatus status = 8 [(validate.rules).enum = {in: [1, 2, 3]}];
string department = 9;
string position = 10;
map<string, string> metadata = 11;
google.protobuf.Timestamp created_at = 12;
google.protobuf.Timestamp updated_at = 13;
google.protobuf.Timestamp last_login_at = 14;
string created_by = 15;
string updated_by = 16;
}
// 创建用户请求
message CreateUserRequest {
string username = 1 [(validate.rules).string = {min_len: 3, max_len: 20, pattern: "^[a-zA-Z0-9_]+$"}];
string email = 2 [(validate.rules).string.email = true];
string full_name = 3 [(validate.rules).string = {min_len: 1, max_len: 100}];
string password = 4 [(validate.rules).string = {min_len: 8, max_len: 128}];
string phone = 5 [(validate.rules).string.pattern = "^1[3-9]\\d{9}$"];
string avatar = 6 [(validate.rules).string.uri = true];
UserRole role = 7 [(validate.rules).enum = {in: [1, 2, 3, 4]}];
string department = 8;
string position = 9;
map<string, string> metadata = 10;
string created_by = 11;
}
// 创建用户响应
message CreateUserResponse {
User user = 1;
string access_token = 2;
int64 expires_in = 3;
}
// 获取用户请求
message GetUserRequest {
string user_id = 1 [(validate.rules).string.uuid = true];
bool include_metadata = 2;
repeated string fields = 3; // 指定返回的字段
}
// 获取用户响应
message GetUserResponse {
User user = 1;
}
// 更新用户请求
message UpdateUserRequest {
string user_id = 1 [(validate.rules).string.uuid = true];
string email = 2 [(validate.rules).string.email = true];
string full_name = 3 [(validate.rules).string = {min_len: 1, max_len: 100}];
string phone = 5 [(validate.rules).string.pattern = "^1[3-9]\\d{9}$"];
string avatar = 6 [(validate.rules).string.uri = true];
string department = 7;
string position = 8;
map<string, string> metadata = 9;
string updated_by = 10;
repeated string fields = 11; // 指定要更新的字段
}
// 更新用户响应
message UpdateUserResponse {
User user = 1;
}
// 删除用户请求
message DeleteUserRequest {
string user_id = 1 [(validate.rules).string.uuid = true];
bool soft_delete = 2; // 软删除标识
string deleted_by = 3;
}
// 删除用户响应
message DeleteUserResponse {
bool success = 1;
string message = 2;
}
// 列出用户请求
message ListUsersRequest {
int32 page = 1 [(validate.rules).int32 = {gt: 0}];
int32 page_size = 2 [(validate.rules).int32 = {gt: 0, lte: 100}];
string search = 3; // 搜索关键词
UserRole role = 4; // 按角色过滤
UserStatus status = 5; // 按状态过滤
string department = 6; // 按部门过滤
string sort_by = 7; // 排序字段
string sort_order = 8; // 排序方向 (asc/desc)
repeated string fields = 9; // 指定返回的字段
}
// 列出用户响应
message ListUsersResponse {
repeated User users = 1;
int64 total = 2;
int32 page = 3;
int32 page_size = 4;
int32 total_pages = 5;
bool has_next = 6;
bool has_prev = 7;
}
// 批量创建用户请求
message BatchCreateUsersRequest {
oneof request {
CreateUserRequest user = 1;
BatchCreateUsersEnd end = 2;
}
}
message BatchCreateUsersEnd {
// 批量创建结束标记
}
// 批量创建用户响应
message BatchCreateUsersResponse {
int64 success_count = 1;
int64 failed_count = 2;
repeated CreateUserResult results = 3;
}
message CreateUserResult {
string user_id = 1;
bool success = 2;
string error_message = 3;
User user = 4;
}
// 流式查询用户请求
message StreamUsersRequest {
string filter = 1; // 过滤条件
repeated string fields = 2; // 返回字段
int32 batch_size = 3; // 批量大小
}
// 搜索用户请求
message SearchUsersRequest {
string query = 1 [(validate.rules).string = {min_len: 1, max_len: 100}];
repeated string fields = 2; // 搜索字段
int32 limit = 3 [(validate.rules).int32 = {gt: 0, lte: 100}];
SearchType search_type = 4;
map<string, string> filters = 5;
}
enum SearchType {
SEARCH_TYPE_UNSPECIFIED = 0;
SEARCH_TYPE_EXACT = 1; // 精确匹配
SEARCH_TYPE_FUZZY = 2; // 模糊匹配
SEARCH_TYPE_PREFIX = 3; // 前缀匹配
}
// 搜索用户响应
message SearchUsersResponse {
repeated User users = 1;
int64 total = 2;
int32 search_time_ms = 3; // 搜索耗时(毫秒)
}
// 更新用户状态请求
message UpdateUserStatusRequest {
string user_id = 1 [(validate.rules).string.uuid = true];
UserStatus status = 2 [(validate.rules).enum = {in: [1, 2, 3]}];
string reason = 3; // 状态变更原因
string updated_by = 4;
}
// 更新用户状态响应
message UpdateUserStatusResponse {
User user = 1;
}
// 用户权限消息
message UserPermission {
string permission_id = 1;
string resource = 2;
string action = 3;
string description = 4;
google.protobuf.Timestamp created_at = 5;
string created_by = 6;
}
// 用户会话消息
message UserSession {
string session_id = 1;
string user_id = 2 [(validate.rules).string.uuid = true];
string device_id = 3;
string device_type = 4; // web, mobile, desktop
string ip_address = 5;
string user_agent = 6;
google.protobuf.Timestamp created_at = 7;
google.protobuf.Timestamp expires_at = 8;
bool is_active = 9;
map<string, string> metadata = 10;
}
---
b.高级服务特性
a.流式数据处理
支持大容量数据的流式传输，避免内存溢出。
b.双向通信
客户端和服务端可以同时发送消息，实现实时交互。
c.元数据传递
支持在调用过程中传递自定义元数据。
d.超时控制
细粒度的超时控制，支持不同操作的差异化配置。
e.高级特性示例
---
// 高级gRPC特性使用示例
package grpc_advanced
import (
"context"
"io"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/metadata"
"google.golang.org/grpc/status"
)
// 流式数据处理服务
type StreamService interface {
// 大文件上传（客户端流式）
UploadFile(stream UploadFileRequest) returns (UploadFileResponse, error)
// 大文件下载（服务端流式）
DownloadFile(*DownloadFileRequest) (DownloadFileResponse, error)
// 实时数据同步（双向流式）
SyncData(stream SyncDataRequest) returns (stream SyncDataResponse, error)
}
// 文件块消息
type FileChunk struct {
ChunkID string `json:"chunk_id"`
ChunkData []byte `json:"chunk_data"`
ChunkIndex int64 `json:"chunk_index"`
TotalChunks int64 `json:"total_chunks"`
FileSize int64 `json:"file_size"`
FileName string `json:"file_name"`
Checksum string `json:"checksum"`
}
// 大文件上传实现
func (s *UserGRPCServer) UploadFile(stream pb.UserService_UploadFileServer) error {
ctx := stream.Context()
// 从元数据获取上传信息
md, ok := metadata.FromIncomingContext(ctx)
if !ok {
return status.Errorf(codes.InvalidArgument, "缺少元数据")
}
userID := md["user_id"][0]
fileName := md["file_name"][0]
fileSize := md["file_size"][0]
s.logger.Infof("开始上传文件: user=%s, file=%s, size=%s", userID, fileName, fileSize)
// 创建文件缓冲区
var fileBuffer []byte
var totalSize int64
var chunkCount int64
// 接收文件块
for {
req, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
return status.Errorf(codes.Internal, "接收文件块失败: %v", err)
}
chunk := req.GetFileChunk()
if chunk == nil {
continue
}
fileBuffer = append(fileBuffer, chunk.ChunkData...)
totalSize += int64(len(chunk.ChunkData))
chunkCount++
// 发送进度反馈
progress := float64(chunkCount) / float64(chunk.TotalChunks) * 100
if err := stream.Send(&pb.UploadFileResponse{
ChunkIndex: chunk.ChunkIndex,
Progress: progress,
Message: fmt.Sprintf("已接收 %d/%d 块", chunk.ChunkIndex, chunk.TotalChunks),
}); err != nil {
return status.Errorf(codes.Internal, "发送进度失败: %v", err)
}
s.logger.Debugf("接收文件块: index=%d, size=%d, progress=%.2f", usageRate*100),
MetricValue: usageRate,
Threshold: 0.9,
Timestamp: time.Now(),
})
}
}
}
// 检查等待时间告警
func (cm *ConnectionMonitor) checkWaitTimeAlert() {
waitCount := atomic.LoadInt64(&cm.metrics.WaitCount)
if waitCount == 0 {
return
}
waitDuration := cm.metrics.WaitDuration
avgWaitTime := time.Duration(int64(waitDuration) / waitCount)
if avgWaitTime > 5*time.Second {
cm.sendAlert(&Alert{
Level: "warning",
Type: "high_wait_time",
Message: fmt.Sprintf("Average wait time is high: %v", avgWaitTime),
MetricValue: float64(avgWaitTime.Nanoseconds()),
Threshold: float64((5 * time.Second).Nanoseconds()),
Timestamp: time.Now(),
})
}
}
// 检查错误率告警
func (cm *ConnectionMonitor) checkErrorRateAlert() {
errors := atomic.LoadInt64(&cm.metrics.QueryErrors)
failures := atomic.LoadInt64(&cm.metrics.ConnectionFailures)
totalErrors := errors + failures
// 这里需要总查询数来计算错误率
// 简化实现，假设有查询计数器
totalQueries := atomic.LoadInt64(&cm.metrics.WaitCount)
if totalQueries > 0 {
errorRate := float64(totalErrors) / float64(totalQueries)
if errorRate > cm.config.ErrorRateThreshold {
cm.sendAlert(&Alert{
Level: "error",
Type: "high_error_rate",
Message: fmt.Sprintf("Error rate is high: %.2f", cpuUsage*100),
MetricValue: cpuUsage,
Threshold: 0.8,
Timestamp: time.Now(),
})
}
}
// 发送告警
func (cm *ConnectionMonitor) sendAlert(alert *Alert) {
cm.mu.RLock()
handlers := make([]AlertHandler, len(cm.alerts))
copy(handlers, cm.alerts)
cm.mu.RUnlock()
for _, handler := range handlers {
if err := handler.HandleAlert(alert); err != nil {
// 记录告警发送失败的错误
fmt.Printf("Failed to send alert: %v\n", err)
}
}
}
// 获取当前指标
func (cm *ConnectionMonitor) GetMetrics() *ConnectionMetrics {
cm.metrics.LastUpdated = time.Now()
return cm.metrics
}
// 记录查询
func (cm *ConnectionMonitor) RecordQuery(duration time.Duration, err error) {
if duration > cm.config.SlowQueryThreshold {
atomic.AddInt64(&cm.metrics.SlowQueries, 1)
}
if err != nil {
atomic.AddInt64(&cm.metrics.QueryErrors, 1)
}
// 更新查询时间统计
// 这里可以实现更复杂的统计逻辑，比如滑动窗口统计
}
// 日志告警处理器
type LogAlertHandler struct {
logger log.Logger
}
func NewLogAlertHandler(logger log.Logger) *LogAlertHandler {
return &LogAlertHandler{logger: logger}
}
func (h *LogAlertHandler) HandleAlert(alert *Alert) error {
level := log.LevelInfo
if alert.Level == "error" {
level = log.LevelError
} else if alert.Level == "warning" {
level = log.LevelWarn
}
h.logger.Log(level,
log.Key("event", "database_alert"),
log.Key("alert_type", alert.Type),
log.Key("alert_level", alert.Level),
log.Key("message", alert.Message),
log.Key("pool_name", alert.PoolName),
log.Key("metric_value", alert.MetricValue),
log.Key("threshold", alert.Threshold),
log.Key("timestamp", alert.Timestamp),
)
return nil
}
// 邮件告警处理器
type EmailAlertHandler struct {
smtpHost string
smtpPort int
username string
password string
from string
to []string
subject string
enabled bool
}
func NewEmailAlertHandler(smtpHost string, smtpPort int, username, password, from string, to []string) *EmailAlertHandler {
return &EmailAlertHandler{
smtpHost: smtpHost,
smtpPort: smtpPort,
username: username,
password: password,
from: from,
to: to,
subject: "Database Alert",
enabled: true,
}
}
func (h *EmailAlertHandler) HandleAlert(alert *Alert) error {
if !h.enabled {
return nil
}
// 构建邮件内容
body := fmt.Sprintf(`
Database Alert
Level: %s
Type: %s
Message: %s
Pool: %s
Metric Value: %.2f
Threshold: %.2f
Time: %s
`,
alert.Level,
alert.Type,
alert.Message,
alert.PoolName,
alert.MetricValue,
alert.Threshold,
alert.Timestamp.Format(time.RFC3339),
)
// 发送邮件（这里简化实现）
fmt.Printf("Sending email alert: %s\n", body)
return nil
}
---
5.3 ORM 框架集成
01.GORM 集成
a.GORM 基础配置
a.数据库连接
配置GORM数据库连接和连接池。
b.日志配置
配置GORM日志级别和格式。
c.插件配置
注册GORM插件和回调。
d.GORM配置示例
---
// orm/gorm.go
package orm
import (
"context"
"fmt"
"time"
"gorm.io/gorm"
"gorm.io/gorm/logger"
"gorm.io/gorm/schema"
"gorm.io/driver/mysql"
"gorm.io/driver/postgres"
"gorm.io/driver/sqlite"
)
// GORM配置
type GORMConfig struct {
Driver string `yaml:"driver"`
DSN string `yaml:"dsn"`
MaxOpenConns int `yaml:"max_open_conns"`
MaxIdleConns int `yaml:"max_idle_conns"`
ConnMaxLifetime time.Duration `yaml:"conn_max_lifetime"`
LogLevel string `yaml:"log_level"`
SlowThreshold time.Duration `yaml:"slow_threshold"`
EnableColor bool `yaml:"enable_color"`
EnableForeignKey bool `yaml:"enable_foreign_key"`
EnablePrepareStmt bool `yaml:"enable_prepare_stmt"`
DisableForeignKeyConstraintWhenMigrating bool `yaml:"disable_foreign_key_constraint_when_migrating"`
}
// 默认GORM配置
func DefaultGORMConfig() *GORMConfig {
return &GORMConfig{
MaxOpenConns: 25,
MaxIdleConns: 10,
ConnMaxLifetime: 5 * time.Minute,
LogLevel: "warn",
SlowThreshold: 100 * time.Millisecond,
EnableColor: true,
EnableForeignKey: true,
EnablePrepareStmt: true,
}
}
// 创建GORM实例
func NewGORM(config *GORMConfig) (*gorm.DB, error) {
if config == nil {
config = DefaultGORMConfig()
}
// 配置日志
logLevel := getGORMLogLevel(config.LogLevel)
gormLogger := logger.New(
&GORMLoggerWriter{
LogLevel: config.LogLevel,
SlowThreshold: config.SlowThreshold,
},
logger.Config{
SlowThreshold: config.SlowThreshold,
LogLevel: logLevel,
IgnoreRecordNotFoundError: true,
Colorful: config.EnableColor,
},
)
// 配置GORM选项
gormConfig := &gorm.Config{
Logger: gormLogger,
NamingStrategy: schema.NamingStrategy{
TablePrefix: "",
SingularTable: false,
NameReplacer: strings.NewReplacer("ID", "Id"),
},
DisableForeignKeyConstraintWhenMigrating: config.DisableForeignKeyConstraintWhenMigrating,
PrepareStmt: config.EnablePrepareStmt,
}
// 创建数据库连接
var dialector gorm.Dialector
switch config.Driver {
case "mysql":
dialector = mysql.Open(config.DSN)
case "postgres":
dialector = postgres.Open(config.DSN)
case "sqlite":
dialector = sqlite.Open(config.DSN)
default:
return nil, fmt.Errorf("unsupported database driver: %s", config.Driver)
}
db, err := gorm.Open(dialector, gormConfig)
if err != nil {
return nil, fmt.Errorf("failed to connect to database: %w", err)
}
// 配置底层连接池
sqlDB, err := db.DB()
if err != nil {
return nil, fmt.Errorf("failed to get underlying sql.DB: %w", err)
}
sqlDB.SetMaxOpenConns(config.MaxOpenConns)
sqlDB.SetMaxIdleConns(config.MaxIdleConns)
sqlDB.SetConnMaxLifetime(config.ConnMaxLifetime)
return db, nil
}
// 获取GORM日志级别
func getGORMLogLevel(level string) logger.LogLevel {
switch level {
case "silent":
return logger.Silent
case "error":
return logger.Error
case "warn":
return logger.Warn
case "info":
return logger.Info
default:
return logger.Warn
}
}
// GORM日志写入器
type GORMLoggerWriter struct {
LogLevel string
SlowThreshold time.Duration
}
func (w *GORMLoggerWriter) Printf(format string, args ...interface{}) {
message := fmt.Sprintf(format, args...)
// 解析日志级别和消息
level, msg := parseGORMLogMessage(message)
switch level {
case "error":
fmt.Printf("[GORM ERROR] %s\n", msg)
case "warn":
if w.LogLevel == "warn" || w.LogLevel == "info" || w.LogLevel == "debug" {
fmt.Printf("[GORM WARN] %s\n", msg)
}
case "info":
if w.LogLevel == "info" || w.LogLevel == "debug" {
fmt.Printf("[GORM INFO] %s\n", msg)
}
}
}
func parseGORMLogMessage(message string) (string, string) {
if strings.Contains(message, "error") {
return "error", message
} else if strings.Contains(message, "warn") {
return "warn", message
} else if strings.Contains(message, "slow") {
return "warn", fmt.Sprintf("[SLOW QUERY] %s", message)
}
return "info", message
}
// GORM管理器
type GORMManager struct {
db *gorm.DB
config *GORMConfig
}
func NewGORMManager(config *GORMConfig) (*GORMManager, error) {
db, err := NewGORM(config)
if err != nil {
return nil, err
}
return &GORMManager{
db: db,
config: config,
}, nil
}
// 获取GORM实例
func (m *GORMManager) GetDB() *gorm.DB {
return m.db
}
// 获取底层SQL DB
func (m *GORMManager) GetSQLDB() (*sql.DB, error) {
return m.db.DB()
}
// 自动迁移
func (m *GORMManager) AutoMigrate(models ...interface{}) error {
return m.db.AutoMigrate(models...)
}
// 健康检查
func (m *GORMManager) HealthCheck(ctx context.Context) error {
sqlDB, err := m.GetSQLDB()
if err != nil {
return err
}
return sqlDB.PingContext(ctx)
}
// 关闭连接
func (m *GORMManager) Close() error {
sqlDB, err := m.GetSQLDB()
if err != nil {
return err
}
return sqlDB.Close()
}
// 获取数据库统计信息
func (m *GORMManager) Stats() map[string]interface{} {
sqlDB, err := m.GetSQLDB()
if err != nil {
return map[string]interface{}{"error": err.Error()}
}
stats := sqlDB.Stats()
return map[string]interface{}{
"max_open_connections": stats.MaxOpenConnections,
"open_connections": stats.OpenConnections,
"in_use": stats.InUse,
"idle": stats.Idle,
"wait_count": stats.WaitCount,
"wait_duration": stats.WaitDuration,
"max_idle_closed": stats.MaxIdleClosed,
"max_lifetime_closed": stats.MaxLifetimeClosed,
}
}
---
b.模型定义
a.基础模型
定义通用的模型字段和方法。
b.软删除模型
支持软删除的模型。
c.时间戳模型
自动管理创建和更新时间。
d.模型定义示例
---
// model/base.go
package model
import (
"time"
"gorm.io/gorm"
)
// 基础模型
type BaseModel struct {
ID uint64 `gorm:"primaryKey;autoIncrement" json:"id"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
DeletedAt gorm.DeletedAt `gorm:"index" json:"deleted_at,omitempty"`
}
// 软删除接口
type SoftDeletable interface {
GetDeletedAt() *gorm.DeletedAt
IsDeleted() bool
}
// 时间戳接口
type Timestampable interface {
GetCreatedAt() time.Time
GetUpdatedAt() time.Time
Touch()
}
// 实现软删除接口
func (m *BaseModel) GetDeletedAt() *gorm.DeletedAt {
return &m.DeletedAt
}
func (m *BaseModel) IsDeleted() bool {
return m.DeletedAt.Valid
}
// 实现时间戳接口
func (m *BaseModel) GetCreatedAt() time.Time {
return m.CreatedAt
}
func (m *BaseModel) GetUpdatedAt() time.Time {
return m.UpdatedAt
}
func (m *BaseModel) Touch() {
m.UpdatedAt = time.Now()
}
// 用户模型
type User struct {
BaseModel
Username string `gorm:"size:50;not null;uniqueIndex" json:"username"`
Email string `gorm:"size:100;not null;uniqueIndex" json:"email"`
Phone string `gorm:"size:20;index" json:"phone"`
Password string `gorm:"size:255;not null" json:"-"`
Avatar string `gorm:"size:255" json:"avatar"`
Status int32 `gorm:"default:1" json:"status"`
Gender int32 `gorm:"default:0" json:"gender"`
Birthday *time.Time `gorm:"index" json:"birthday,omitempty"`
// 关联关系
Profile *UserProfile `gorm:"foreignKey:UserID;constraint:OnDelete:CASCADE" json:"profile,omitempty"`
Roles []Role `gorm:"many2many:user_roles;" json:"roles,omitempty"`
Orders []Order `gorm:"foreignKey:UserID" json:"orders,omitempty"`
// 计算字段
Age int32 `gorm:"-" json:"age,omitempty"`
}
// 用户资料
type UserProfile struct {
BaseModel
UserID uint64 `gorm:"not null;uniqueIndex" json:"user_id"`
FirstName string `gorm:"size:50;not null" json:"first_name"`
LastName string `gorm:"size:50;not null" json:"last_name"`
Nickname string `gorm:"size:50" json:"nickname"`
Bio string `gorm:"type:text" json:"bio"`
Address string `gorm:"size:255" json:"address"`
City string `gorm:"size:100" json:"city"`
Country string `gorm:"size:100" json:"country"`
PostalCode string `gorm:"size:20" json:"postal_code"`
Preferences string `gorm:"type:json" json:"preferences"`
User User `gorm:"foreignKey:UserID;references:ID" json:"user,omitempty"`
}
// 角色模型
type Role struct {
BaseModel
Name string `gorm:"size:50;not null;uniqueIndex" json:"name"`
Code string `gorm:"size:50;not null;uniqueIndex" json:"code"`
Description string `gorm:"type:text" json:"description"`
Status int32 `gorm:"default:1" json:"status"`
Permissions []Permission `gorm:"many2many:role_permissions;" json:"permissions,omitempty"`
Users []User `gorm:"many2many:user_roles;" json:"users,omitempty"`
}
// 权限模型
type Permission struct {
BaseModel
Name string `gorm:"size:100;not null;uniqueIndex" json:"name"`
Code string `gorm:"size:100;not null;uniqueIndex" json:"code"`
Resource string `gorm:"size:100;not null;index" json:"resource"`
Action string `gorm:"size:50;not null;index" json:"action"`
Description string `gorm:"type:text" json:"description"`
Status int32 `gorm:"default:1" json:"status"`
Roles []Role `gorm:"many2many:role_permissions;" json:"roles,omitempty"`
}
// 订单模型
type Order struct {
BaseModel
OrderNo string `gorm:"size:32;not null;uniqueIndex" json:"order_no"`
UserID uint64 `gorm:"not null;index" json:"user_id"`
TotalAmount float64 `gorm:"type:decimal(10,2);not null" json:"total_amount"`
Status int32 `gorm:"default:1" json:"status"`
PaymentID *uint64 `gorm:"index" json:"payment_id,omitempty"`
PaidAt *time.Time `json:"paid_at,omitempty"`
ShippedAt *time.Time `json:"shipped_at,omitempty"`
CompletedAt *time.Time `json:"completed_at,omitempty"`
// 关联关系
User User `gorm:"foreignKey:UserID;references:ID" json:"user,omitempty"`
Payment *Payment `gorm:"foreignKey:PaymentID;references:ID" json:"payment,omitempty"`
Items []OrderItem `gorm:"foreignKey:OrderID;constraint:OnDelete:CASCADE" json:"items,omitempty"`
Address *OrderAddress `gorm:"foreignKey:OrderID;constraint:OnDelete:CASCADE" json:"address,omitempty"`
}
// 订单项
type OrderItem struct {
BaseModel
OrderID uint64 `gorm:"not null;index" json:"order_id"`
ProductID uint64 `gorm:"not null;index" json:"product_id"`
ProductName string `gorm:"size:255;not null" json:"product_name"`
ProductPrice float64 `gorm:"type:decimal(10,2);not null" json:"product_price"`
Quantity int32 `gorm:"not null" json:"quantity"`
Subtotal float64 `gorm:"type:decimal(10,2);not null" json:"subtotal"`
// 关联关系
Order Order `gorm:"foreignKey:OrderID;references:ID" json:"order,omitempty"`
Product Product `gorm:"foreignKey:ProductID;references:ID" json:"product,omitempty"`
}
// 订单地址
type OrderAddress struct {
BaseModel
OrderID uint64 `gorm:"not null;uniqueIndex" json:"order_id"`
Recipient string `gorm:"size:100;not null" json:"recipient"`
Phone string `gorm:"size:20;not null" json:"phone"`
Address string `gorm:"size:255;not null" json:"address"`
City string `gorm:"size:100;not null" json:"city"`
Province string `gorm:"size:100;not null" json:"province"`
Country string `gorm:"size:100;not null" json:"country"`
PostalCode string `gorm:"size:20" json:"postal_code"`
IsDefault bool `gorm:"default:false" json:"is_default"`
// 关联关系
Order Order `gorm:"foreignKey:OrderID;references:ID" json:"order,omitempty"`
}
// 产品模型
type Product struct {
BaseModel
Name string `gorm:"size:255;not null;index" json:"name"`
Code string `gorm:"size:100;not null;uniqueIndex" json:"code"`
Description string `gorm:"type:text" json:"description"`
Price float64 `gorm:"type:decimal(10,2);not null" json:"price"`
Stock int32 `gorm:"default:0" json:"stock"`
CategoryID *uint64 `gorm:"index" json:"category_id,omitempty"`
Status int32 `gorm:"default:1" json:"status"`
Images string `gorm:"type:json" json:"images"`
Attributes string `gorm:"type:json" json:"attributes"`
// 关联关系
Category *ProductCategory `gorm:"foreignKey:CategoryID;references:ID" json:"category,omitempty"`
Items []OrderItem `gorm:"foreignKey:ProductID" json:"items,omitempty"`
}
// 产品分类
type ProductCategory struct {
BaseModel
Name string `gorm:"size:100;not null" json:"name"`
Code string `gorm:"size:100;not null;uniqueIndex" json:"code"`
Description string `gorm:"type:text" json:"description"`
ParentID *uint64 `gorm:"index" json:"parent_id,omitempty"`
Level int32 `gorm:"default:1" json:"level"`
Sort int32 `gorm:"default:0" json:"sort"`
Status int32 `gorm:"default:1" json:"status"`
Parent *ProductCategory `gorm:"foreignKey:ParentID;references:ID" json:"parent,omitempty"`
Children []ProductCategory `gorm:"foreignKey:ParentID;references:ID" json:"children,omitempty"`
Products []Product `gorm:"foreignKey:CategoryID;references:ID" json:"products,omitempty"`
}
// 支付模型
type Payment struct {
BaseModel
PaymentNo string `gorm:"size:32;not null;uniqueIndex" json:"payment_no"`
OrderID uint64 `gorm:"not null;uniqueIndex" json:"order_id"`
UserID uint64 `gorm:"not null;index" json:"user_id"`
Amount float64 `gorm:"type:decimal(10,2);not null" json:"amount"`
Method string `gorm:"size:50;not null" json:"method"`
Status int32 `gorm:"default:1" json:"status"`
TransactionID string `gorm:"size:100;index" json:"transaction_id,omitempty"`
Gateway string `gorm:"size:50" json:"gateway"`
PaidAt *time.Time `json:"paid_at,omitempty"`
FailedAt *time.Time `json:"failed_at,omitempty"`
// 关联关系
Order Order `gorm:"foreignKey:OrderID;references:ID" json:"order,omitempty"`
}
// 模型钩子
func (u *User) BeforeCreate(tx *gorm.DB) error {
// 自动计算年龄
if u.Birthday != nil {
now := time.Now()
age := now.Year() - u.Birthday.Year()
if now.Month() < u.Birthday.Month() ||
(now.Month() == u.Birthday.Month() && now.Day() < u.Birthday.Day()) {
age--
}
u.Age = int32(age)
}
return nil
}
func (u *User) BeforeUpdate(tx *gorm.DB) error {
// 重新计算年龄
if u.Birthday != nil {
now := time.Now()
age := now.Year() - u.Birthday.Year()
if now.Month() < u.Birthday.Month() ||
(now.Month() == u.Birthday.Month() && now.Day() < u.Birthday.Day()) {
age--
}
u.Age = int32(age)
}
return nil
}
func (o *Order) AfterCreate(tx *gorm.DB) error {
// 订单创建后的处理逻辑
// 例如：发送确认邮件、减少库存等
return nil
}
func (p *Product) AfterUpdate(tx *gorm.DB) error {
// 产品更新后的处理逻辑
// 例如：更新缓存、发送通知等
return nil
}
// 模型方法
func (u *User) IsActive() bool {
return u.Status == 1
}
func (u *User) HasRole(roleCode string) bool {
for _, role := range u.Roles {
if role.Code == roleCode {
return true
}
}
return false
}
func (o *Order) CanBeCancelled() bool {
return o.Status == 1 // 待支付状态可以取消
}
func (o *Order) CanBeShipped() bool {
return o.Status == 2 // 已支付状态可以发货
}
func (p *Product) IsInStock() bool {
return p.Stock > 0
}
func (p *Product) DecreaseStock(quantity int32) error {
if p.Stock < quantity {
return fmt.Errorf("insufficient stock")
}
p.Stock -= quantity
return nil
}
---
c.查询操作
a.基础查询
使用GORM进行基础的CRUD操作。
b.关联查询
处理模型之间的关联关系查询。
c.复杂查询
构建复杂的数据库查询。
d.查询操作示例
---
// query/gorm_query.go
package query
import (
"context"
"fmt"
"strings"
"time"
"gorm.io/gorm"
"github.com/example/internal/model"
)
// 用户查询器
type UserQuery struct {
db *gorm.DB
}
func NewUserQuery(db *gorm.DB) *UserQuery {
return &UserQuery{db: db}
}
// 创建用户
func (q *UserQuery) Create(ctx context.Context, user *model.User) error {
return q.db.WithContext(ctx).Create(user).Error
}
// 批量创建用户
func (q *UserQuery) CreateBatch(ctx context.Context, users []*model.User) error {
return q.db.WithContext(ctx).CreateInBatches(users, 100).Error
}
// 根据ID查找用户
func (q *UserQuery) FindByID(ctx context.Context, id uint64) (*model.User, error) {
var user model.User
err := q.db.WithContext(ctx).
Preload("Profile").
Preload("Roles").
Preload("Roles.Permissions").
First(&user, id).Error
if err != nil {
return nil, err
}
return &user, nil
}
// 根据用户名查找用户
func (q *UserQuery) FindByUsername(ctx context.Context, username string) (*model.User, error) {
var user model.User
err := q.db.WithContext(ctx).
Preload("Profile").
Preload("Roles").
Where("username = ?", username).
First(&user).Error
if err != nil {
return nil, err
}
return &user, nil
}
// 根据邮箱查找用户
func (q *UserQuery) FindByEmail(ctx context.Context, email string) (*model.User, error) {
var user model.User
err := q.db.WithContext(ctx).
Preload("Profile").
Preload("Roles").
Where("email = ?", email).
First(&user).Error
if err != nil {
return nil, err
}
return &user, nil
}
// 更新用户
func (q *UserQuery) Update(ctx context.Context, user *model.User) error {
return q.db.WithContext(ctx).Save(user).Error
}
// 更新用户部分字段
func (q *UserQuery) UpdateFields(ctx context.Context, id uint64, updates map[string]interface{}) error {
return q.db.WithContext(ctx).Model(&model.User{}).Where("id = ?", id).Updates(updates).Error
}
// 删除用户（软删除）
func (q *UserQuery) Delete(ctx context.Context, id uint64) error {
return q.db.WithContext(ctx).Delete(&model.User{}, id).Error
}
// 永久删除用户
func (q *UserQuery) HardDelete(ctx context.Context, id uint64) error {
return q.db.WithContext(ctx).Unscoped().Delete(&model.User{}, id).Error
}
// 分页查询用户
func (q *UserQuery) FindPage(ctx context.Context, req *UserPageRequest) (*UserPageResponse, error) {
var users []*model.User
var total int64
query := q.db.WithContext(ctx).Model(&model.User{})
// 应用筛选条件
if req.Status != nil {
query = query.Where("status = ?", *req.Status)
}
if req.Gender != nil {
query = query.Where("gender = ?", *req.Gender)
}
if req.Search != "" {
query = query.Where("username LIKE ? OR email LIKE ?", "%"+req.Search+"%", "%"+req.Search+"%")
}
if req.StartTime != nil {
query = query.Where("created_at >= ?", *req.StartTime)
}
if req.EndTime != nil {
query = query.Where("created_at <= ?", *req.EndTime)
}
// 计算总数
if err := query.Count(&total).Error; err != nil {
return nil, err
}
// 应用排序
orderClause := "id DESC"
if req.Sort != "" {
orderClause = req.Sort
if req.Order != "" {
orderClause += " " + req.Order
}
}
// 分页查询
offset := (req.Page - 1) * req.PageSize
err := query.Preload("Profile").
Preload("Roles").
Order(orderClause).
Offset(offset).
Limit(req.PageSize).
Find(&users).Error
if err != nil {
return nil, err
}
return &UserPageResponse{
Users: users,
Total: total,
Page: req.Page,
PageSize: req.PageSize,
TotalPages: (total + int64(req.PageSize) - 1) / int64(req.PageSize),
}, nil
}
// 查找活跃用户
func (q *UserQuery) FindActiveUsers(ctx context.Context, limit int) ([]*model.User, error) {
var users []*model.User
err := q.db.WithContext(ctx).
Where("status = ?", 1).
Order("created_at DESC").
Limit(limit).
Preload("Profile").
Find(&users).Error
return users, err
}
// 根据角色查找用户
func (q *UserQuery) FindByRole(ctx context.Context, roleCode string) ([]*model.User, error) {
var users []*model.User
err := q.db.WithContext(ctx).
Joins("JOIN user_roles ON users.id = user_roles.user_id").
Joins("JOIN roles ON user_roles.role_id = roles.id").
Where("roles.code = ?", roleCode).
Preload("Profile").
Preload("Roles").
Find(&users).Error
return users, err
}
// 订单查询器
type OrderQuery struct {
db *gorm.DB
}
func NewOrderQuery(db *gorm.DB) *OrderQuery {
return &OrderQuery{db: db}
}
// 创建订单
func (q *OrderQuery) Create(ctx context.Context, order *model.Order) error {
return q.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// 创建订单
if err := tx.Create(order).Error; err != nil {
return err
}
// 创建订单项
for _, item := range order.Items {
item.OrderID = order.ID
if err := tx.Create(item).Error; err != nil {
return err
}
}
// 创建订单地址
if order.Address != nil {
order.Address.OrderID = order.ID
if err := tx.Create(order.Address).Error; err != nil {
return err
}
}
return nil
})
}
// 根据ID查找订单
func (q *OrderQuery) FindByID(ctx context.Context, id uint64) (*model.Order, error) {
var order model.Order
err := q.db.WithContext(ctx).
Preload("User").
Preload("User.Profile").
Preload("Items").
Preload("Items.Product").
Preload("Address").
Preload("Payment").
First(&order, id).Error
if err != nil {
return nil, err
}
return &order, nil
}
// 根据订单号查找订单
func (q *OrderQuery) FindByOrderNo(ctx context.Context, orderNo string) (*model.Order, error) {
var order model.Order
err := q.db.WithContext(ctx).
Preload("User").
Preload("Items").
Preload("Address").
Preload("Payment").
Where("order_no = ?", orderNo).
First(&order).Error
if err != nil {
return nil, err
}
return &order, nil
}
// 查找用户订单
func (q *OrderQuery) FindByUserID(ctx context.Context, userID uint64, req *OrderPageRequest) (*OrderPageResponse, error) {
var orders []*model.Order
var total int64
query := q.db.WithContext(ctx).Model(&model.Order{}).Where("user_id = ?", userID)
// 应用筛选条件
if req.Status != nil {
query = query.Where("status = ?", *req.Status)
}
if req.StartTime != nil {
query = query.Where("created_at >= ?", *req.StartTime)
}
if req.EndTime != nil {
query = query.Where("created_at <= ?", *req.EndTime)
}
// 计算总数
if err := query.Count(&total).Error; err != nil {
return nil, err
}
// 应用排序
orderClause := "created_at DESC"
if req.Sort != "" {
orderClause = req.Sort
if req.Order != "" {
orderClause += " " + req.Order
}
}
// 分页查询
offset := (req.Page - 1) * req.PageSize
err := query.Preload("Items").
Preload("Payment").
Order(orderClause).
Offset(offset).
Limit(req.PageSize).
Find(&orders).Error
if err != nil {
return nil, err
}
return &OrderPageResponse{
Orders: orders,
Total: total,
Page: req.Page,
PageSize: req.PageSize,
TotalPages: (total + int64(req.PageSize) - 1) / int64(req.PageSize),
}, nil
}
// 更新订单状态
func (q *OrderQuery) UpdateStatus(ctx context.Context, id uint64, status int32) error {
updates := map[string]interface{}{
"status": status,
}
switch status {
case 3: // 已发货
updates["shipped_at"] = time.Now()
case 4: // 已完成
updates["completed_at"] = time.Now()
}
return q.db.WithContext(ctx).Model(&model.Order{}).Where("id = ?", id).Updates(updates).Error
}
// 复杂查询示例：统计用户消费
func (q *OrderQuery) GetUserSpending(ctx context.Context, userID uint64, startTime, endTime *time.Time) (float64, error) {
var totalAmount float64
query := q.db.WithContext(ctx).Model(&model.Order{}).
Where("user_id = ?", userID).
Where("status IN ?", []int32{3, 4}) // 已完成或已发货
if startTime != nil {
query = query.Where("created_at >= ?", *startTime)
}
if endTime != nil {
query = query.Where("created_at <= ?", *endTime)
}
err := query.Select("COALESCE(SUM(total_amount), 0)").Scan(&totalAmount).Error
return totalAmount, err
}
// 产品查询器
type ProductQuery struct {
db *gorm.DB
}
func NewProductQuery(db *gorm.DB) *ProductQuery {
return &ProductQuery{db: db}
}
// 搜索产品
func (q *ProductQuery) Search(ctx context.Context, req *ProductSearchRequest) (*ProductSearchResponse, error) {
var products []*model.Product
var total int64
query := q.db.WithContext(ctx).Model(&model.Product{}).Where("status = ?", 1)
// 关键词搜索
if req.Keyword != "" {
query = query.Where("name LIKE ? OR description LIKE ?",
"%"+req.Keyword+"%", "%"+req.Keyword+"%")
}
// 分类筛选
if req.CategoryID != nil {
query = query.Where("category_id = ?", *req.CategoryID)
}
// 价格范围
if req.MinPrice != nil {
query = query.Where("price >= ?", *req.MinPrice)
}
if req.MaxPrice != nil {
query = query.Where("price <= ?", *req.MaxPrice)
}
// 库存筛选
if req.InStock != nil && *req.InStock {
query = query.Where("stock > 0")
}
// 计算总数
if err := query.Count(&total).Error; err != nil {
return nil, err
}
// 应用排序
orderClause := "id DESC"
switch req.SortBy {
case "price_asc":
orderClause = "price ASC"
case "price_desc":
orderClause = "price DESC"
case "name":
orderClause = "name ASC"
case "created_at":
orderClause = "created_at DESC"
}
// 分页查询
offset := (req.Page - 1) * req.PageSize
err := query.Preload("Category").
Order(orderClause).
Offset(offset).
Limit(req.PageSize).
Find(&products).Error
if err != nil {
return nil, err
}
return &ProductSearchResponse{
Products: products,
Total: total,
Page: req.Page,
PageSize: req.PageSize,
TotalPages: (total + int64(req.PageSize) - 1) / int64(req.PageSize),
}, nil
}
// 更新产品库存
func (q *ProductQuery) UpdateStock(ctx context.Context, id uint64, quantity int32) error {
return q.db.WithContext(ctx).Model(&model.Product{}).
Where("id = ?", id).
UpdateColumn("stock", gorm.Expr("stock + ?", quantity)).Error
}
// 扣减库存
func (q *ProductQuery) DecreaseStock(ctx context.Context, id uint64, quantity int32) error {
result := q.db.WithContext(ctx).Model(&model.Product{}).
Where("id = ? AND stock >= ?", id, quantity).
UpdateColumn("stock", gorm.Expr("stock - ?", quantity))
if result.Error != nil {
return result.Error
}
if result.RowsAffected == 0 {
return fmt.Errorf("insufficient stock for product %d", id)
}
return nil
}
// 请求和响应结构体
type UserPageRequest struct {
Page int `json:"page" binding:"min=1"`
PageSize int `json:"page_size" binding:"min=1,max=100"`
Status *int32 `json:"status"`
Gender *int32 `json:"gender"`
Search string `json:"search"`
StartTime *time.Time `json:"start_time"`
EndTime *time.Time `json:"end_time"`
Sort string `json:"sort"`
Order string `json:"order"`
}
type UserPageResponse struct {
Users []*model.User `json:"users"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int64 `json:"total_pages"`
}
type OrderPageRequest struct {
Page int `json:"page" binding:"min=1"`
PageSize int `json:"page_size" binding:"min=1,max=100"`
Status *int32 `json:"status"`
StartTime *time.Time `json:"start_time"`
EndTime *time.Time `json:"end_time"`
Sort string `json:"sort"`
Order string `json:"order"`
}
type OrderPageResponse struct {
Orders []*model.Order `json:"orders"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int64 `json:"total_pages"`
}
type ProductSearchRequest struct {
Page int `json:"page" binding:"min=1"`
PageSize int `json:"page_size" binding:"min=1,max=100"`
Keyword string `json:"keyword"`
CategoryID *uint64 `json:"category_id"`
MinPrice *float64 `json:"min_price"`
MaxPrice *float64 `json:"max_price"`
InStock *bool `json:"in_stock"`
SortBy string `json:"sort_by"`
}
type ProductSearchResponse struct {
Products []*model.Product `json:"products"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int64 `json:"total_pages"`
}
---
5.4 Repository 模式实现
01.Repository 基础架构
a.接口定义
a.通用Repository接口
定义通用的数据操作接口。
b.领域特定接口
为特定领域定义专门的接口。
c.泛型接口支持
使用Go泛型提高代码复用性。
d.Repository接口示例
---
// repository/interfaces.go
package repository
import (
"context"
"github.com/example/internal/model"
"github.com/example/internal/query"
)
// 基础Repository接口
type IRepository[T any, ID comparable] interface {
// 基础CRUD操作
Create(ctx context.Context, entity *T) error
Update(ctx context.Context, entity *T) error
Delete(ctx context.Context, id ID) error
FindByID(ctx context.Context, id ID) (*T, error)
// 查询操作
FindOne(ctx context.Context, condition Condition) (*T, error)
FindMany(ctx context.Context, condition Condition) ([]*T, error)
Count(ctx context.Context, condition Condition) (int64, error)
Exists(ctx context.Context, condition Condition) (bool, error)
// 批量操作
CreateMany(ctx context.Context, entities []*T) error
UpdateMany(ctx context.Context, entities []*T) error
DeleteMany(ctx context.Context, ids []ID) error
// 分页查询
FindPage(ctx context.Context, page PageRequest) (*PageResult[*T], error)
}
// 软删除Repository接口
type ISoftDeletableRepository[T any, ID comparable] interface {
IRepository[T, ID]
// 软删除操作
SoftDelete(ctx context.Context, id ID) error
SoftDeleteMany(ctx context.Context, ids []ID) error
// 恢复操作
Restore(ctx context.Context, id ID) error
RestoreMany(ctx context.Context, ids []ID) error
// 查询包含软删除的数据
FindByIDWithDeleted(ctx context.Context, id ID) (*T, error)
FindOneWithDeleted(ctx context.Context, condition Condition) (*T, error)
FindManyWithDeleted(ctx context.Context, condition Condition) ([]*T, error)
}
// 时间戳Repository接口
type ITimestampedRepository[T any, ID comparable] interface {
IRepository[T, ID]
// 按时间查询
FindByTimeRange(ctx context.Context, startTime, endTime time.Time) ([]*T, error)
FindCreatedAfter(ctx context.Context, after time.Time) ([]*T, error)
FindUpdatedAfter(ctx context.Context, after time.Time) ([]*T, error)
// 统计操作
CountByDate(ctx context.Context, date time.Time) (int64, error)
CountByTimeRange(ctx context.Context, startTime, endTime time.Time) (int64, error)
}
// 缓存Repository接口
type ICachedRepository[T any, ID comparable] interface {
IRepository[T, ID]
// 缓存操作
InvalidateCache(ctx context.Context, id ID) error
InvalidateCachePattern(ctx context.Context, pattern string) error
WarmupCache(ctx context.Context, ids []ID) error
RefreshCache(ctx context.Context, id ID) error
// 批量缓存操作
InvalidateCacheMany(ctx context.Context, ids []ID) error
WarmupCacheMany(ctx context.Context, ids []ID) error
}
// 事务Repository接口
type ITransactionalRepository[T any, ID comparable] interface {
IRepository[T, ID]
// 事务操作
WithTransaction(ctx context.Context, fn func(ctx context.Context, repo ITransactionalRepository[T, ID]) error) error
BeginTransaction(ctx context.Context) (ITransaction, error)
}
// 事务接口
type ITransaction interface {
Commit() error
Rollback() error
Context() context.Context
IsActive() bool
}
// 用户Repository接口
type IUserRepository interface {
ISoftDeletableRepository[*model.User, uint64]
ITimestampedRepository[*model.User, uint64]
ICachedRepository[*model.User, uint64]
ITransactionalRepository[*model.User, uint64]
// 用户特定操作
FindByUsername(ctx context.Context, username string) (*model.User, error)
FindByEmail(ctx context.Context, email string) (*model.User, error)
FindByPhone(ctx context.Context, phone string) (*model.User, error)
FindActiveUsers(ctx context.Context, limit int) ([]*model.User, error)
FindByRole(ctx context.Context, roleCode string) ([]*model.User, error)
// 更新用户状态
UpdateStatus(ctx context.Context, id uint64, status int32) error
UpdatePassword(ctx context.Context, id uint64, password string) error
// 检查是否存在
ExistsByUsername(ctx context.Context, username string) (bool, error)
ExistsByEmail(ctx context.Context, email string) (bool, error)
ExistsByPhone(ctx context.Context, phone string) (bool, error)
// 用户统计
CountByStatus(ctx context.Context, status int32) (int64, error)
CountByDateRange(ctx context.Context, startTime, endTime time.Time) (int64, error)
}
// 订单Repository接口
type IOrderRepository interface {
IRepository[*model.Order, uint64]
ITimestampedRepository[*model.Order, uint64]
ITransactionalRepository[*model.Order, uint64]
// 订单特定操作
FindByOrderNo(ctx context.Context, orderNo string) (*model.Order, error)
FindByUserID(ctx context.Context, userID uint64, page PageRequest) (*PageResult[*model.Order], error)
FindByStatus(ctx context.Context, status int32, page PageRequest) (*PageResult[*model.Order], error)
FindByTimeRange(ctx context.Context, startTime, endTime time.Time, page PageRequest) (*PageResult[*model.Order], error)
// 订单状态管理
UpdateStatus(ctx context.Context, id uint64, status int32) error
UpdatePaymentID(ctx context.Context, id uint64, paymentID uint64) error
// 订单统计
CountByUserID(ctx context.Context, userID uint64) (int64, error)
SumAmountByUserID(ctx context.Context, userID uint64) (float64, error)
CountByStatus(ctx context.Context, status int32) (int64, error)
// 业务统计
GetDailyOrderCount(ctx context.Context, date time.Time) (int64, error)
GetDailyOrderAmount(ctx context.Context, date time.Time) (float64, error)
GetMonthlyOrderStats(ctx context.Context, year, month int) (*MonthlyOrderStats, error)
}
// 产品Repository接口
type IProductRepository interface {
IRepository[*model.Product, uint64]
ICachedRepository[*model.Product, uint64]
// 产品特定操作
FindByCode(ctx context.Context, code string) (*model.Product, error)
FindByCategoryID(ctx context.Context, categoryID uint64, page PageRequest) (*PageResult[*model.Product], error)
FindInStock(ctx context.Context, page PageRequest) (*PageResult[*model.Product], error)
Search(ctx context.Context, req *ProductSearchRequest) (*ProductSearchResult, error)
// 库存管理
UpdateStock(ctx context.Context, id uint64, quantity int32) error
DecreaseStock(ctx context.Context, id uint64, quantity int32) error
IncreaseStock(ctx context.Context, id uint64, quantity int32) error
// 价格管理
UpdatePrice(ctx context.Context, id uint64, price float64) error
GetPriceHistory(ctx context.Context, id uint64, limit int) ([]*ProductPriceHistory, error)
// 产品统计
CountByCategory(ctx context.Context, categoryID uint64) (int64, error)
GetTopSellingProducts(ctx context.Context, limit int) ([]*model.Product, error)
}
// 支付Repository接口
type IPaymentRepository interface {
IRepository[*model.Payment, uint64]
ITimestampedRepository[*model.Payment, uint64]
// 支付特定操作
FindByPaymentNo(ctx context.Context, paymentNo string) (*model.Payment, error)
FindByOrderID(ctx context.Context, orderID uint64) (*model.Payment, error)
FindByTransactionID(ctx context.Context, transactionID string) (*model.Payment, error)
FindByStatus(ctx context.Context, status int32, page PageRequest) (*PageResult[*model.Payment], error)
// 支付状态管理
UpdateStatus(ctx context.Context, id uint64, status int32) error
UpdateTransactionID(ctx context.Context, id uint64, transactionID string) error
// 支付统计
CountByStatus(ctx context.Context, status int32) (int64, error)
SumAmountByDate(ctx context.Context, date time.Time) (float64, error)
GetPaymentStats(ctx context.Context, startTime, endTime time.Time) (*PaymentStats, error)
}
// 条件接口
type Condition interface {
Build() (string, []interface{})
And(condition Condition) Condition
Or(condition Condition) Condition
Not() Condition
}
// 分页请求
type PageRequest struct {
Page int `json:"page" binding:"min=1"`
PageSize int `json:"page_size" binding:"min=1,max=100"`
Sort []SortField `json:"sort"`
Filter Condition `json:"filter"`
Includes []string `json:"includes"`
Excludes []string `json:"excludes"`
}
// 排序字段
type SortField struct {
Field string `json:"field"`
Order string `json:"order"` // ASC, DESC
}
// 分页结果
type PageResult[T any] struct {
Items []T `json:"items"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int `json:"total_pages"`
}
// 产品搜索请求
type ProductSearchRequest struct {
Keyword string `json:"keyword"`
CategoryID *uint64 `json:"category_id"`
MinPrice *float64 `json:"min_price"`
MaxPrice *float64 `json:"max_price"`
InStock *bool `json:"in_stock"`
SortBy string `json:"sort_by"`
Page int `json:"page"`
PageSize int `json:"page_size"`
}
// 产品搜索结果
type ProductSearchResult struct {
Products []*model.Product `json:"products"`
Total int64 `json:"total"`
Page int `json:"page"`
PageSize int `json:"page_size"`
TotalPages int64 `json:"total_pages"`
}
// 月度订单统计
type MonthlyOrderStats struct {
Year int `json:"year"`
Month int `json:"month"`
OrderCount int64 `json:"order_count"`
TotalAmount float64 `json:"total_amount"`
AvgAmount float64 `json:"avg_amount"`
}
// 产品价格历史
type ProductPriceHistory struct {
ID uint64 `json:"id"`
ProductID uint64 `json:"product_id"`
Price float64 `json:"price"`
CreatedAt time.Time `json:"created_at"`
}
// 支付统计
type PaymentStats struct {
TotalCount int64 `json:"total_count"`
TotalAmount float64 `json:"total_amount"`
SuccessCount int64 `json:"success_count"`
SuccessAmount float64 `json:"success_amount"`
FailedCount int64 `json:"failed_count"`
FailedAmount float64 `json:"failed_amount"`
SuccessRate float64 `json:"success_rate"`
}
---
b.基础Repository实现
a.通用实现
实现通用的Repository基类。
b.查询构建器集成
集成查询构建器进行复杂查询。
c.错误处理
统一的错误处理机制。
d.基础实现示例
---
// repository/base.go
package repository
import (
"context"
"errors"
"fmt"
"reflect"
"time"
"gorm.io/gorm"
"github.com/example/internal/query"
)
// 基础Repository实现
type BaseRepository[T any, ID comparable] struct {
db *gorm.DB
query *query.QueryBuilder
mapper *query.DataMapper[T]
}
// 创建基础Repository
func NewBaseRepository[T any, ID comparable](db *gorm.DB, tableName string) *BaseRepository[T, ID] {
return &BaseRepository[T, ID]{
db: db,
query: query.NewQueryBuilder(tableName),
mapper: query.NewDataMapper[T](),
}
}
// 创建实体
func (r *BaseRepository[T, ID]) Create(ctx context.Context, entity *T) error {
return r.db.WithContext(ctx).Create(entity).Error
}
// 更新实体
func (r *BaseRepository[T, ID]) Update(ctx context.Context, entity *T) error {
return r.db.WithContext(ctx).Save(entity).Error
}
// 删除实体
func (r *BaseRepository[T, ID]) Delete(ctx context.Context, id ID) error {
return r.db.WithContext(ctx).Delete(new(T), id).Error
}
// 根据ID查找实体
func (r *BaseRepository[T, ID]) FindByID(ctx context.Context, id ID) (*T, error) {
var entity T
err := r.db.WithContext(ctx).First(&entity, id).Error
if err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrRecordNotFound
}
return nil, err
}
return &entity, nil
}
// 根据条件查找单个实体
func (r *BaseRepository[T, ID]) FindOne(ctx context.Context, condition Condition) (*T, error) {
var entity T
query, params := condition.Build()
err := r.db.WithContext(ctx).Where(query, params...).First(&entity).Error
if err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrRecordNotFound
}
return nil, err
}
return &entity, nil
}
// 根据条件查找多个实体
func (r *BaseRepository[T, ID]) FindMany(ctx context.Context, condition Condition) ([]*T, error) {
var entities []*T
query, params := condition.Build()
err := r.db.WithContext(ctx).Where(query, params...).Find(&entities).Error
if err != nil {
return nil, err
}
return entities, nil
}
// 统计数量
func (r *BaseRepository[T, ID]) Count(ctx context.Context, condition Condition) (int64, error) {
var count int64
query, params := condition.Build()
err := r.db.WithContext(ctx).Model(new(T)).Where(query, params...).Count(&count).Error
return count, err
}
// 检查是否存在
func (r *BaseRepository[T, ID]) Exists(ctx context.Context, condition Condition) (bool, error) {
count, err := r.Count(ctx, condition)
return count > 0, err
}
// 批量创建
func (r *BaseRepository[T, ID]) CreateMany(ctx context.Context, entities []*T) error {
if len(entities) == 0 {
return nil
}
return r.db.WithContext(ctx).CreateInBatches(entities, 100).Error
}
// 批量更新
func (r *BaseRepository[T, ID]) UpdateMany(ctx context.Context, entities []*T) error {
if len(entities) == 0 {
return nil
}
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
for _, entity := range entities {
if err := tx.Save(entity).Error; err != nil {
return err
}
}
return nil
})
}
// 批量删除
func (r *BaseRepository[T, ID]) DeleteMany(ctx context.Context, ids []ID) error {
if len(ids) == 0 {
return nil
}
return r.db.WithContext(ctx).Delete(new(T), ids).Error
}
// 分页查询
func (r *BaseRepository[T, ID]) FindPage(ctx context.Context, page PageRequest) (*PageResult[*T], error) {
var entities []*T
var total int64
query := r.db.WithContext(ctx).Model(new(T))
// 应用筛选条件
if page.Filter != nil {
filterQuery, filterParams := page.Filter.Build()
query = query.Where(filterQuery, filterParams...)
}
// 计算总数
if err := query.Count(&total).Error; err != nil {
return nil, err
}
// 应用排序
if len(page.Sort) > 0 {
orderClause := r.buildOrderClause(page.Sort)
query = query.Order(orderClause)
}
// 应用分页
offset := (page.Page - 1) * page.PageSize
if err := query.Offset(offset).Limit(page.PageSize).Find(&entities).Error; err != nil {
return nil, err
}
// 处理包含和排除字段
if len(page.Includes) > 0 || len(page.Excludes) > 0 {
entities = r.applyFieldSelection(entities, page.Includes, page.Excludes)
}
return &PageResult[*T]{
Items: entities,
Total: total,
Page: page.Page,
PageSize: page.PageSize,
TotalPages: (total + int64(page.PageSize) - 1) / int64(page.PageSize),
}, nil
}
// 构建排序子句
func (r *BaseRepository[T, ID]) buildOrderClause(sortFields []SortField) string {
var clauses []string
for _, sort := range sortFields {
direction := "ASC"
if sort.Order == "DESC" {
direction = "DESC"
}
clauses = append(clauses, fmt.Sprintf("%s %s", sort.Field, direction))
}
return strings.Join(clauses, ", ")
}
// 应用字段选择
func (r *BaseRepository[T, ID]) applyFieldSelection(entities []*T, includes, excludes []string) []*T {
// 这里简化实现，实际可能需要更复杂的字段选择逻辑
return entities
}
// 获取数据库连接
func (r *BaseRepository[T, ID]) GetDB() *gorm.DB {
return r.db
}
// 软删除Repository实现
type SoftDeletableRepository[T any, ID comparable] struct {
*BaseRepository[T, ID]
}
func NewSoftDeletableRepository[T any, ID comparable](db *gorm.DB, tableName string) *SoftDeletableRepository[T, ID] {
return &SoftDeletableRepository[T, ID]{
BaseRepository: NewBaseRepository[T, ID](db, tableName),
}
}
// 软删除
func (r *SoftDeletableRepository[T, ID]) SoftDelete(ctx context.Context, id ID) error {
return r.db.WithContext(ctx).Delete(new(T), id).Error
}
// 批量软删除
func (r *SoftDeletableRepository[T, ID]) SoftDeleteMany(ctx context.Context, ids []ID) error {
if len(ids) == 0 {
return nil
}
return r.db.WithContext(ctx).Delete(new(T), ids).Error
}
// 恢复
func (r *SoftDeletableRepository[T, ID]) Restore(ctx context.Context, id ID) error {
return r.db.WithContext(ctx).Unscoped().Model(new(T)).Where("id = ?", id).Update("deleted_at", nil).Error
}
// 批量恢复
func (r *SoftDeletableRepository[T, ID]) RestoreMany(ctx context.Context, ids []ID) error {
if len(ids) == 0 {
return nil
}
return r.db.WithContext(ctx).Unscoped().Model(new(T)).Where("id IN ?", ids).Update("deleted_at", nil).Error
}
// 查找包含软删除的记录
func (r *SoftDeletableRepository[T, ID]) FindByIDWithDeleted(ctx context.Context, id ID) (*T, error) {
var entity T
err := r.db.WithContext(ctx).Unscoped().First(&entity, id).Error
if err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrRecordNotFound
}
return nil, err
}
return &entity, nil
}
// 根据条件查找包含软删除的记录
func (r *SoftDeletableRepository[T, ID]) FindOneWithDeleted(ctx context.Context, condition Condition) (*T, error) {
var entity T
query, params := condition.Build()
err := r.db.WithContext(ctx).Unscoped().Where(query, params...).First(&entity).Error
if err != nil {
if errors.Is(err, gorm.ErrRecordNotFound) {
return nil, ErrRecordNotFound
}
return nil, err
}
return &entity, nil
}
// 根据条件查找多个包含软删除的记录
func (r *SoftDeletableRepository[T, ID]) FindManyWithDeleted(ctx context.Context, condition Condition) ([]*T, error) {
var entities []*T
query, params := condition.Build()
err := r.db.WithContext(ctx).Unscoped().Where(query, params...).Find(&entities).Error
if err != nil {
return nil, err
}
return entities, nil
}
// 时间戳Repository实现
type TimestampedRepository[T any, ID comparable] struct {
*BaseRepository[T, ID]
}
func NewTimestampedRepository[T any, ID comparable](db *gorm.DB, tableName string) *TimestampedRepository[T, ID] {
return &TimestampedRepository[T, ID]{
BaseRepository: NewBaseRepository[T, ID](db, tableName),
}
}
// 按时间范围查找
func (r *TimestampedRepository[T, ID]) FindByTimeRange(ctx context.Context, startTime, endTime time.Time) ([]*T, error) {
var entities []*T
err := r.db.WithContext(ctx).
Where("created_at >= ? AND created_at <= ?", startTime, endTime).
Find(&entities).Error
return entities, err
}
// 查找创建时间之后的记录
func (r *TimestampedRepository[T, ID]) FindCreatedAfter(ctx context.Context, after time.Time) ([]*T, error) {
var entities []*T
err := r.db.WithContext(ctx).Where("created_at > ?", after).Find(&entities).Error
return entities, err
}
// 查找更新时间之后的记录
func (r *TimestampedRepository[T, ID]) FindUpdatedAfter(ctx context.Context, after time.Time) ([]*T, error) {
var entities []*T
err := r.db.WithContext(ctx).Where("updated_at > ?", after).Find(&entities).Error
return entities, err
}
// 按日期统计
func (r *TimestampedRepository[T, ID]) CountByDate(ctx context.Context, date time.Time) (int64, error) {
startTime := time.Date(date.Year(), date.Month(), date.Day(), 0, 0, 0, 0, date.Location())
endTime := startTime.Add(24 * time.Hour)
var count int64
err := r.db.WithContext(ctx).Model(new(T)).
Where("created_at >= ? AND created_at < ?", startTime, endTime).
Count(&count).Error
return count, err
}
// 按时间范围统计
func (r *TimestampedRepository[T, ID]) CountByTimeRange(ctx context.Context, startTime, endTime time.Time) (int64, error) {
var count int64
err := r.db.WithContext(ctx).Model(new(T)).
Where("created_at >= ? AND created_at <= ?", startTime, endTime).
Count(&count).Error
return count, err
}
// 缓存Repository实现
type CachedRepository[T any, ID comparable] struct {
*BaseRepository[T, ID]
cache ICache
ttl time.Duration
}
func NewCachedRepository[T any, ID comparable](db *gorm.DB, cache ICache, ttl time.Duration, tableName string) *CachedRepository[T, ID] {
return &CachedRepository[T, ID]{
BaseRepository: NewBaseRepository[T, ID](db, tableName),
cache: cache,
ttl: ttl,
}
}
// 根据ID查找（带缓存）
func (r *CachedRepository[T, ID]) FindByID(ctx context.Context, id ID) (*T, error) {
// 尝试从缓存获取
cacheKey := r.buildCacheKey("id", id)
if cached, err := r.cache.Get(ctx, cacheKey); err == nil {
return cached.(*T), nil
}
// 从数据库获取
entity, err := r.BaseRepository.FindByID(ctx, id)
if err != nil {
return nil, err
}
// 设置缓存
r.cache.Set(ctx, cacheKey, entity, r.ttl)
return entity, nil
}
// 创建实体
func (r *CachedRepository[T, ID]) Create(ctx context.Context, entity *T) error {
err := r.BaseRepository.Create(ctx, entity)
if err != nil {
return err
}
// 清理相关缓存
r.invalidateEntityCache(ctx, entity)
return nil
}
// 更新实体
func (r *CachedRepository[T, ID]) Update(ctx context.Context, entity *T) error {
err := r.BaseRepository.Update(ctx, entity)
if err != nil {
return err
}
// 清理相关缓存
r.invalidateEntityCache(ctx, entity)
return nil
}
// 删除实体
func (r *CachedRepository[T, ID]) Delete(ctx context.Context, id ID) error {
err := r.BaseRepository.Delete(ctx, id)
if err != nil {
return err
}
// 清理相关缓存
r.InvalidateCache(ctx, id)
return nil
}
// 失效缓存
func (r *CachedRepository[T, ID]) InvalidateCache(ctx context.Context, id ID) error {
cacheKey := r.buildCacheKey("id", id)
return r.cache.Delete(ctx, cacheKey)
}
// 按模式失效缓存
func (r *CachedRepository[T, ID]) InvalidateCachePattern(ctx context.Context, pattern string) error {
return r.cache.DeletePattern(ctx, pattern)
}
// 预热缓存
func (r *CachedRepository[T, ID]) WarmupCache(ctx context.Context, ids []ID) error {
for _, id := range ids {
if _, err := r.FindByID(ctx, id); err != nil {
return err
}
}
return nil
}
// 刷新缓存
func (r *CachedRepository[T, ID]) RefreshCache(ctx context.Context, id ID) error {
cacheKey := r.buildCacheKey("id", id)
r.cache.Delete(ctx, cacheKey)
_, err := r.FindByID(ctx, id)
return err
}
// 批量失效缓存
func (r *CachedRepository[T, ID]) InvalidateCacheMany(ctx context.Context, ids []ID) error {
for _, id := range ids {
if err := r.InvalidateCache(ctx, id); err != nil {
return err
}
}
return nil
}
// 批量预热缓存
func (r *CachedRepository[T, ID]) WarmupCacheMany(ctx context.Context, ids []ID) error {
return r.WarmupCache(ctx, ids)
}
// 构建缓存键
func (r *CachedRepository[T, ID]) buildCacheKey(prefix string, key interface{}) string {
return fmt.Sprintf("%s:%s:%v", r.getTableName(), prefix, key)
}
// 获取表名
func (r *CachedRepository[T, ID]) getTableName() string {
var t T
return r.db.NamingStrategy.TableName(reflect.TypeOf(t).Name())
}
// 失效实体相关缓存
func (r *CachedRepository[T, ID]) invalidateEntityCache(ctx context.Context, entity *T) {
// 获取实体ID
id := r.getEntityID(entity)
if id != nil {
r.InvalidateCache(ctx, id)
}
// 这里可以添加其他相关缓存的清理逻辑
}
// 获取实体ID（简化实现）
func (r *CachedRepository[T, ID]) getEntityID(entity *T) ID {
// 这里需要根据具体的实体结构来获取ID
// 简化实现，实际可能需要使用反射
var zero ID
return zero
}
// 事务Repository实现
type TransactionalRepository[T any, ID comparable] struct {
*BaseRepository[T, ID]
}
func NewTransactionalRepository[T any, ID comparable](db *gorm.DB, tableName string) *TransactionalRepository[T, ID] {
return &TransactionalRepository[T, ID]{
BaseRepository: NewBaseRepository[T, ID](db, tableName),
}
}
// 在事务中执行操作
func (r *TransactionalRepository[T, ID]) WithTransaction(ctx context.Context, fn func(ctx context.Context, repo ITransactionalRepository[T, ID]) error) error {
return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// 创建事务专用的Repository
txRepo := NewTransactionalRepository[T, ID](tx, "")
return fn(ctx, txRepo)
})
}
// 开始事务
func (r *TransactionalRepository[T, ID]) BeginTransaction(ctx context.Context) (ITransaction, error) {
tx := r.db.WithContext(ctx).Begin()
if tx.Error != nil {
return nil, tx.Error
}
return &GormTransaction{tx: tx}, nil
}
// GORM事务实现
type GormTransaction struct {
tx *gorm.DB
}
func (t *GormTransaction) Commit() error {
return t.tx.Commit().Error
}
func (t *GormTransaction) Rollback() error {
return t.tx.Rollback().Error
}
func (t *GormTransaction) Context() context.Context {
return t.tx.Statement.Context
}
func (t *GormTransaction) IsActive() bool {
return t.tx != nil
}
// 错误定义
var (
ErrRecordNotFound = errors.New("record not found")
ErrInvalidID = errors.New("invalid id")
ErrDuplicateKey = errors.New("duplicate key")
ErrConstraint = errors.New("constraint violation")
)
// 缓存接口
type ICache interface {
Get(ctx context.Context, key string) (interface{}, error)
Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
Delete(ctx context.Context, key string) error
DeletePattern(ctx context.Context, pattern string) error
Exists(ctx context.Context, key string) (bool, error)
Clear(ctx context.Context) error
}
---
5.5 缓存系统集成
01.缓存架构设计
a.缓存层次
a.L1缓存（内存缓存）
应用进程内的内存缓存，访问速度最快。
b.L2缓存（分布式缓存）
Redis等分布式缓存服务，支持多实例共享。
c.L3缓存（CDN缓存）
内容分发网络，主要用于静态资源。
d.缓存架构示例
---
// cache/architecture.go
package cache
import (
"context"
"encoding/json"
"fmt"
"time"
)
// 缓存层级定义
type CacheLevel int
const (
CacheLevelL1 CacheLevel = iota // 内存缓存
CacheLevelL2 // 分布式缓存
CacheLevelL3 // CDN缓存
)
// 缓存策略
type CacheStrategy struct {
Levels []CacheLevel `yaml:"levels"` // 缓存层级
L1TTL time.Duration `yaml:"l1_ttl"` // L1缓存过期时间
L2TTL time.Duration `yaml:"l2_ttl"` // L2缓存过期时间
EnableL1 bool `yaml:"enable_l1"` // 启用L1缓存
EnableL2 bool `yaml:"enable_l2"` // 启用L2缓存
EnableAsync bool `yaml:"enable_async"` // 异步刷新
HitRatio float64 `yaml:"hit_ratio"` // 目标命中率
}
// 多层缓存接口
type MultiLevelCache interface {
Get(ctx context.Context, key string) (interface{}, error)
Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
Delete(ctx context.Context, key string) error
DeletePattern(ctx context.Context, pattern string) error
GetWithLoader(ctx context.Context, key string, loader CacheLoader) (interface{}, error)
Refresh(ctx context.Context, key string) error
GetStats() CacheStats
Clear(ctx context.Context) error
}
// 缓存加载器
type CacheLoader interface {
Load(ctx context.Context, key string) (interface{}, error)
}
// 缓存统计
type CacheStats struct {
L1Stats LevelCacheStats `json:"l1_stats"`
L2Stats LevelCacheStats `json:"l2_stats"`
TotalStats LevelCacheStats `json:"total_stats"`
}
// 单层缓存统计
type LevelCacheStats struct {
Hits int64 `json:"hits"`
Misses int64 `json:"misses"`
Sets int64 `json:"sets"`
Deletes int64 `json:"deletes"`
HitRatio float64 `json:"hit_ratio"`
Size int64 `json:"size"`
MaxSize int64 `json:"max_size"`
Evictions int64 `json:"evictions"`
}
// 缓存配置
type CacheConfig struct {
L1Config *MemoryCacheConfig `yaml:"l1_config"`
L2Config *RedisCacheConfig `yaml:"l2_config"`
Strategy *CacheStrategy `yaml:"strategy"`
KeyPrefix string `yaml:"key_prefix"`
EnableMetrics bool `yaml:"enable_metrics"`
EnableTracing bool `yaml:"enable_tracing"`
}
// 内存缓存配置
type MemoryCacheConfig struct {
MaxSize int `yaml:"max_size"` // 最大条目数
MaxMemory int64 `yaml:"max_memory"` // 最大内存(字节)
TTL time.Duration `yaml:"ttl"` // 默认TTL
CleanupInterval time.Duration `yaml:"cleanup_interval"` // 清理间隔
EnableLRU bool `yaml:"enable_lru"` // 启用LRU淘汰
}
// Redis缓存配置
type RedisCacheConfig struct {
Addresses []string `yaml:"addresses"` // Redis地址
Password string `yaml:"password"` // 密码
DB int `yaml:"db"` // 数据库
PoolSize int `yaml:"pool_size"` // 连接池大小
MinIdle int `yaml:"min_idle"` // 最小空闲连接
MaxRetries int `yaml:"max_retries"` // 最大重试次数
DialTimeout time.Duration `yaml:"dial_timeout"` // 连接超时
ReadTimeout time.Duration `yaml:"read_timeout"` // 读超时
WriteTimeout time.Duration `yaml:"write_timeout"` // 写超时
IdleTimeout time.Duration `yaml:"idle_timeout"` // 空闲超时
EnableCluster bool `yaml:"enable_cluster"` // 启用集群
}
// 默认缓存配置
func DefaultCacheConfig() *CacheConfig {
return &CacheConfig{
L1Config: &MemoryCacheConfig{
MaxSize: 10000,
MaxMemory: 100 * 1024 * 1024, // 100MB
TTL: 5 * time.Minute,
CleanupInterval: 1 * time.Minute,
EnableLRU: true,
},
L2Config: &RedisCacheConfig{
Addresses: []string{"localhost:6379"},
DB: 0,
PoolSize: 10,
MinIdle: 5,
MaxRetries: 3,
DialTimeout: 5 * time.Second,
ReadTimeout: 3 * time.Second,
WriteTimeout: 3 * time.Second,
IdleTimeout: 5 * time.Minute,
EnableCluster: false,
},
Strategy: &CacheStrategy{
Levels: []CacheLevel{CacheLevelL1, CacheLevelL2},
L1TTL: 5 * time.Minute,
L2TTL: 30 * time.Minute,
EnableL1: true,
EnableL2: true,
EnableAsync: false,
HitRatio: 0.8,
},
KeyPrefix: "app:",
EnableMetrics: true,
EnableTracing: false,
}
}
---
b.内存缓存实现
a.LRU算法
最近最少使用淘汰算法。
b.TTL管理
生存时间管理。
c.并发安全
保证多线程环境下的数据安全。
d.内存缓存示例
---
// cache/memory_cache.go
package cache
import (
"container/list"
"context"
"hash/fnv"
"sync"
"time"
)
// 内存缓存条目
type cacheEntry struct {
key string
value interface{}
expiration *time.Time
accessTime time.Time
element *list.Element // LRU链表元素
}
// 内存缓存实现
type MemoryCache struct {
mu sync.RWMutex
data map[string]*cacheEntry
lru *list.List // LRU链表
maxSize int // 最大条目数
maxMemory int64 // 最大内存
currentSize int64 // 当前内存
ttl time.Duration // 默认TTL
stats *LevelCacheStats // 统计信息
cleanupStop chan struct{} // 停止清理信号
enableLRU bool // 启用LRU
}
// 创建内存缓存
func NewMemoryCache(config *MemoryCacheConfig) *MemoryCache {
cache := &MemoryCache{
data: make(map[string]*cacheEntry),
lru: list.New(),
maxSize: config.MaxSize,
maxMemory: config.MaxMemory,
ttl: config.TTL,
stats: &LevelCacheStats{},
cleanupStop: make(chan struct{}),
enableLRU: config.EnableLRU,
}
// 启动定期清理
go cache.startCleanup(config.CleanupInterval)
return cache
}
// 获取缓存值
func (c *MemoryCache) Get(ctx context.Context, key string) (interface{}, error) {
c.mu.Lock()
defer c.mu.Unlock()
entry, exists := c.data[key]
if !exists {
c.stats.Misses++
return nil, ErrCacheNotFound
}
// 检查是否过期
if entry.expiration != nil && time.Now().After(*entry.expiration) {
c.removeEntry(entry)
c.stats.Misses++
return nil, ErrCacheExpired
}
// 更新访问时间和LRU位置
entry.accessTime = time.Now()
if c.enableLRU {
c.lru.MoveToFront(entry.element)
}
c.stats.Hits++
return entry.value, nil
}
// 设置缓存值
func (c *MemoryCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error {
c.mu.Lock()
defer c.mu.Unlock()
// 计算条目大小
entrySize := c.calculateEntrySize(key, value)
// 检查内存限制
if c.maxMemory > 0 && c.currentSize+entrySize > c.maxMemory {
c.evictLRU(entrySize)
}
// 设置过期时间
var expiration *time.Time
if ttl > 0 {
exp := time.Now().Add(ttl)
expiration = &exp
} else if c.ttl > 0 {
exp := time.Now().Add(c.ttl)
expiration = &exp
}
// 更新现有条目或创建新条目
if entry, exists := c.data[key]; exists {
// 更新现有条目
c.currentSize -= c.calculateEntrySize(entry.key, entry.value)
entry.value = value
entry.expiration = expiration
entry.accessTime = time.Now()
c.currentSize += entrySize
if c.enableLRU {
c.lru.MoveToFront(entry.element)
}
} else {
// 创建新条目
entry := &cacheEntry{
key: key,
value: value,
expiration: expiration,
accessTime: time.Now(),
}
// 添加到LRU链表
if c.enableLRU {
entry.element = c.lru.PushFront(key)
}
c.data[key] = entry
c.currentSize += entrySize
// 检查大小限制
if c.maxSize > 0 && len(c.data) > c.maxSize {
c.evictLRUBySize()
}
}
c.stats.Sets++
return nil
}
// 删除缓存值
func (c *MemoryCache) Delete(ctx context.Context, key string) error {
c.mu.Lock()
defer c.mu.Unlock()
if entry, exists := c.data[key]; exists {
c.removeEntry(entry)
c.stats.Deletes++
return nil
}
return ErrCacheNotFound
}
// 按模式删除
func (c *MemoryCache) DeletePattern(ctx context.Context, pattern string) error {
c.mu.Lock()
defer c.mu.Unlock()
keysToDelete := make([]string, 0)
for key := range c.data {
if c.matchPattern(key, pattern) {
keysToDelete = append(keysToDelete, key)
}
}
for _, key := range keysToDelete {
if entry := c.data[key]; entry != nil {
c.removeEntry(entry)
c.stats.Deletes++
}
}
return nil
}
// 清空缓存
func (c *MemoryCache) Clear(ctx context.Context) error {
c.mu.Lock()
defer c.mu.Unlock()
c.data = make(map[string]*cacheEntry)
c.lru = list.New()
c.currentSize = 0
return nil
}
// 获取统计信息
func (c *MemoryCache) GetStats() *LevelCacheStats {
c.mu.RLock()
defer c.mu.RUnlock()
total := c.stats.Hits + c.stats.Misses
hitRatio := float64(0)
if total > 0 {
hitRatio = float64(c.stats.Hits) / float64(total)
}
return &LevelCacheStats{
Hits: c.stats.Hits,
Misses: c.stats.Misses,
Sets: c.stats.Sets,
Deletes: c.stats.Deletes,
HitRatio: hitRatio,
Size: int64(len(c.data)),
MaxSize: int64(c.maxSize),
Evictions: c.stats.Evictions,
}
}
// 移除条目
func (c *MemoryCache) removeEntry(entry *cacheEntry) {
c.currentSize -= c.calculateEntrySize(entry.key, entry.value)
delete(c.data, entry.key)
if c.enableLRU && entry.element != nil {
c.lru.Remove(entry.element)
}
}
// LRU淘汰
func (c *MemoryCache) evictLRU(requiredSize int64) {
if !c.enableLRU {
return
}
for c.lru.Len() > 0 && c.currentSize+requiredSize > c.maxMemory {
back := c.lru.Back()
if back == nil {
break
}
key := back.Value.(string)
if entry := c.data[key]; entry != nil {
c.removeEntry(entry)
c.stats.Evictions++
}
}
}
// 按大小LRU淘汰
func (c *MemoryCache) evictLRUBySize() {
if !c.enableLRU {
return
}
for c.lru.Len() > 0 && len(c.data) > c.maxSize {
back := c.lru.Back()
if back == nil {
break
}
key := back.Value.(string)
if entry := c.data[key]; entry != nil {
c.removeEntry(entry)
c.stats.Evictions++
}
}
}
// 计算条目大小
func (c *MemoryCache) calculateEntrySize(key string, value interface{}) int64 {
// 简化的大小计算
keySize := int64(len(key))
valueSize := int64(0)
if value != nil {
// 这里可以更精确地计算value的大小
// 简化处理，假设平均值为100字节
valueSize = 100
}
return keySize + valueSize + 100 // 额外开销
}
// 模式匹配
func (c *MemoryCache) matchPattern(key, pattern string) bool {
// 简单的通配符匹配，支持*和?
return simpleMatch(key, pattern)
}
// 简单匹配实现
func simpleMatch(text, pattern string) bool {
if pattern == "*" {
return true
}
// 这里可以实现更复杂的模式匹配逻辑
return len(text) >= len(pattern) && text[:len(pattern)] == pattern
}
// 定期清理过期条目
func (c *MemoryCache) startCleanup(interval time.Duration) {
if interval <= 0 {
return
}
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
case <-ticker.C:
c.cleanup()
case <-c.cleanupStop:
return
}
}
}
// 清理过期条目
func (c *MemoryCache) cleanup() {
c.mu.Lock()
defer c.mu.Unlock()
now := time.Now()
keysToDelete := make([]string, 0)
for key, entry := range c.data {
if entry.expiration != nil && now.After(*entry.expiration) {
keysToDelete = append(keysToDelete, key)
}
}
for _, key := range keysToDelete {
if entry := c.data[key]; entry != nil {
c.removeEntry(entry)
c.stats.Evictions++
}
}
}
// 关闭缓存
func (c *MemoryCache) Close() error {
close(c.cleanupStop)
return nil
}
// 缓存错误定义
var (
ErrCacheNotFound = fmt.Errorf("cache not found")
ErrCacheExpired = fmt.Errorf("cache expired")
ErrCacheFull = fmt.Errorf("cache full")
)
// 带TTL的内存缓存
type TTLMemoryCache struct {
*MemoryCache
defaultTTL time.Duration
}
// 创建带TTL的内存缓存
func NewTTLMemoryCache(config *MemoryCacheConfig) *TTLMemoryCache {
return &TTLMemoryCache{
MemoryCache: NewMemoryCache(config),
defaultTTL: config.TTL,
}
}
// 设置带默认TTL的缓存值
func (c *TTLMemoryCache) SetWithDefaultTTL(ctx context.Context, key string, value interface{}) error {
return c.Set(ctx, key, value, c.defaultTTL)
}
// 并发安全的内存缓存
type ConcurrentMemoryCache struct {
*MemoryCache
}
// 创建并发安全的内存缓存
func NewConcurrentMemoryCache(config *MemoryCacheConfig) *ConcurrentMemoryCache {
return &ConcurrentMemoryCache{
MemoryCache: NewMemoryCache(config),
}
}
// 分片内存缓存
type ShardedMemoryCache struct {
shards []*MemoryCache
count int
}
// 创建分片内存缓存
func NewShardedMemoryCache(config *MemoryCacheConfig, shardCount int) *ShardedMemoryCache {
if shardCount <= 0 {
shardCount = 16
}
shards := make([]*MemoryCache, shardCount)
for i := 0; i < shardCount; i++ {
// 每个分片使用配置的1/shardCount大小
shardConfig := *config
shardConfig.MaxSize = config.MaxSize / shardCount
shardConfig.MaxMemory = config.MaxMemory / int64(shardCount)
shards[i] = NewMemoryCache(&shardConfig)
}
return &ShardedMemoryCache{
shards: shards,
count: shardCount,
}
}
// 获取分片
func (c *ShardedMemoryCache) getShard(key string) *MemoryCache {
hash := fnv.New32a()
hash.Write([]byte(key))
return c.shards[int(hash.Sum32())%c.count]
}
// 获取缓存值
func (c *ShardedMemoryCache) Get(ctx context.Context, key string) (interface{}, error) {
return c.getShard(key).Get(ctx, key)
}
// 设置缓存值
func (c *ShardedMemoryCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error {
return c.getShard(key).Set(ctx, key, value, ttl)
}
// 删除缓存值
func (c *ShardedMemoryCache) Delete(ctx context.Context, key string) error {
return c.getShard(key).Delete(ctx, key)
}
// 按模式删除
func (c *ShardedMemoryCache) DeletePattern(ctx context.Context, pattern string) error {
var errors []error
for _, shard := range c.shards {
if err := shard.DeletePattern(ctx, pattern); err != nil {
errors = append(errors, err)
}
}
if len(errors) > 0 {
return fmt.Errorf("some shards failed: %v", errors)
}
return nil
}
// 清空缓存
func (c *ShardedMemoryCache) Clear(ctx context.Context) error {
var errors []error
for _, shard := range c.shards {
if err := shard.Clear(ctx); err != nil {
errors = append(errors, err)
}
}
if len(errors) > 0 {
return fmt.Errorf("some shards failed: %v", errors)
}
return nil
}
// 获取聚合统计信息
func (c *ShardedMemoryCache) GetStats() *LevelCacheStats {
totalStats := &LevelCacheStats{}
for _, shard := range c.shards {
stats := shard.GetStats()
totalStats.Hits += stats.Hits
totalStats.Misses += stats.Misses
totalStats.Sets += stats.Sets
totalStats.Deletes += stats.Deletes
totalStats.Size += stats.Size
totalStats.MaxSize += stats.MaxSize
totalStats.Evictions += stats.Evictions
}
// 计算命中率
total := totalStats.Hits + totalStats.Misses
if total > 0 {
totalStats.HitRatio = float64(totalStats.Hits) / float64(total)
}
return totalStats
}
// 关闭缓存
func (c *ShardedMemoryCache) Close() error {
var errors []error
for _, shard := range c.shards {
if err := shard.Close(); err != nil {
errors = append(errors, err)
}
}
if len(errors) > 0 {
return fmt.Errorf("some shards failed to close: %v", errors)
}
return nil
}
---
c.Redis缓存实现
a.连接管理
Redis连接池管理。
b.集群支持
Redis集群和哨兵模式支持。
c.管道操作
Redis管道批量操作。
d.Redis缓存示例
---
// cache/redis_cache.go
package cache
import (
"context"
"encoding/json"
"fmt"
"strconv"
"strings"
"time"
"github.com/go-redis/redis/v8"
)
// Redis缓存实现
type RedisCache struct {
client redis.Cmdable
config *RedisCacheConfig
stats *LevelCacheStats
metrics CacheMetrics
}
// 创建Redis缓存
func NewRedisCache(config *RedisCacheConfig) (*RedisCache, error) {
var client redis.Cmdable
var err error
if config.EnableCluster {
client = redis.NewClusterClient(&redis.ClusterOptions{
Addrs: config.Addresses,
Password: config.Password,
PoolSize: config.PoolSize,
MinIdleConns: config.MinIdle,
MaxRetries: config.MaxRetries,
DialTimeout: config.DialTimeout,
ReadTimeout: config.ReadTimeout,
WriteTimeout: config.WriteTimeout,
IdleTimeout: config.IdleTimeout,
PoolTimeout: config.IdleTimeout,
})
} else {
client = redis.NewClient(&redis.Options{
Addr: config.Addresses[0],
Password: config.Password,
DB: config.DB,
PoolSize: config.PoolSize,
MinIdleConns: config.MinIdle,
MaxRetries: config.MaxRetries,
DialTimeout: config.DialTimeout,
ReadTimeout: config.ReadTimeout,
WriteTimeout: config.WriteTimeout,
IdleTimeout: config.IdleTimeout,
PoolTimeout: config.IdleTimeout,
})
}
// 测试连接
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := client.Ping(ctx).Err(); err != nil {
return nil, fmt.Errorf("failed to connect to Redis: %w", err)
}
return &RedisCache{
client: client,
config: config,
stats: &LevelCacheStats{},
metrics: NewCacheMetrics(),
}, nil
}
// 获取缓存值
func (r *RedisCache) Get(ctx context.Context, key string) (interface{}, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("get", time.Since(start))
}()
result, err := r.client.Get(ctx, key).Result()
if err != nil {
if err == redis.Nil {
r.stats.Misses++
return nil, ErrCacheNotFound
}
r.stats.Misses++
return nil, fmt.Errorf("redis get error: %w", err)
}
// 尝试解析JSON
var value interface{}
if err := json.Unmarshal([]byte(result), &value); err != nil {
// 如果不是JSON，直接返回字符串
value = result
}
r.stats.Hits++
return value, nil
}
// 设置缓存值
func (r *RedisCache) Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("set", time.Since(start))
}()
// 序列化值
var data []byte
var err error
if str, ok := value.(string); ok {
data = []byte(str)
} else {
data, err = json.Marshal(value)
if err != nil {
return fmt.Errorf("failed to marshal value: %w", err)
}
}
// 设置缓存
if err := r.client.Set(ctx, key, data, ttl).Err(); err != nil {
return fmt.Errorf("redis set error: %w", err)
}
r.stats.Sets++
return nil
}
// 删除缓存值
func (r *RedisCache) Delete(ctx context.Context, key string) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("delete", time.Since(start))
}()
result, err := r.client.Del(ctx, key).Result()
if err != nil {
return fmt.Errorf("redis delete error: %w", err)
}
if result > 0 {
r.stats.Deletes++
return nil
}
return ErrCacheNotFound
}
// 按模式删除
func (r *RedisCache) DeletePattern(ctx context.Context, pattern string) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("delete_pattern", time.Since(start))
}()
keys, err := r.client.Keys(ctx, pattern).Result()
if err != nil {
return fmt.Errorf("redis keys error: %w", err)
}
if len(keys) == 0 {
return nil
}
result, err := r.client.Del(ctx, keys...).Result()
if err != nil {
return fmt.Errorf("redis delete pattern error: %w", err)
}
r.stats.Deletes += int64(result)
return nil
}
// 清空缓存
func (r *RedisCache) Clear(ctx context.Context) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("clear", time.Since(start))
}()
if err := r.client.FlushDB(ctx).Err(); err != nil {
return fmt.Errorf("redis flush error: %w", err)
}
// 重置统计
r.stats = &LevelCacheStats{}
return nil
}
// 批量获取
func (r *RedisCache) MGet(ctx context.Context, keys []string) (map[string]interface{}, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("mget", time.Since(start))
}()
if len(keys) == 0 {
return make(map[string]interface{}), nil
}
results, err := r.client.MGet(ctx, keys...).Result()
if err != nil {
return nil, fmt.Errorf("redis mget error: %w", err)
}
values := make(map[string]interface{})
for i, result := range results {
if result == nil {
continue
}
key := keys[i]
str, ok := result.(string)
if !ok {
values[key] = result
continue
}
// 尝试解析JSON
var value interface{}
if err := json.Unmarshal([]byte(str), &value); err != nil {
// 如果不是JSON，直接返回字符串
value = str
}
values[key] = value
r.stats.Hits++
}
// 记录未命中
r.stats.Misses += int64(len(keys) - len(values))
return values, nil
}
// 批量设置
func (r *RedisCache) MSet(ctx context.Context, items map[string]interface{}, ttl time.Duration) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("mset", time.Since(start))
}()
if len(items) == 0 {
return nil
}
pipe := r.client.Pipeline()
for key, value := range items {
// 序列化值
var data []byte
var err error
if str, ok := value.(string); ok {
data = []byte(str)
} else {
data, err = json.Marshal(value)
if err != nil {
return fmt.Errorf("failed to marshal value for key %s: %w", key, err)
}
}
pipe.Set(ctx, key, data, ttl)
}
if _, err := pipe.Exec(ctx); err != nil {
return fmt.Errorf("redis mset error: %w", err)
}
r.stats.Sets += int64(len(items))
return nil
}
// 原子递增
func (r *RedisCache) Incr(ctx context.Context, key string) (int64, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("incr", time.Since(start))
}()
result, err := r.client.Incr(ctx, key).Result()
if err != nil {
return 0, fmt.Errorf("redis incr error: %w", err)
}
r.stats.Sets++
return result, nil
}
// 原子递增指定值
func (r *RedisCache) IncrBy(ctx context.Context, key string, value int64) (int64, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("incr_by", time.Since(start))
}()
result, err := r.client.IncrBy(ctx, key, value).Result()
if err != nil {
return 0, fmt.Errorf("redis incrby error: %w", err)
}
r.stats.Sets++
return result, nil
}
// 获取剩余过期时间
func (r *RedisCache) TTL(ctx context.Context, key string) (time.Duration, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("ttl", time.Since(start))
}()
result, err := r.client.TTL(ctx, key).Result()
if err != nil {
return 0, fmt.Errorf("redis ttl error: %w", err)
}
return result, nil
}
// 检查key是否存在
func (r *RedisCache) Exists(ctx context.Context, key string) (bool, error) {
start := time.Now()
defer func() {
r.metrics.recordLatency("exists", time.Since(start))
}()
result, err := r.client.Exists(ctx, key).Result()
if err != nil {
return false, fmt.Errorf("redis exists error: %w", err)
}
return result > 0, nil
}
// 设置key过期时间
func (r *RedisCache) Expire(ctx context.Context, key string, ttl time.Duration) error {
start := time.Now()
defer func() {
r.metrics.recordLatency("expire", time.Since(start))
}()
result, err := r.client.Expire(ctx, key, ttl).Result()
if err != nil {
return fmt.Errorf("redis expire error: %w", err)
}
if !result {
return ErrCacheNotFound
}
return nil
}
// 获取统计信息
func (r *RedisCache) GetStats() *LevelCacheStats {
r.mu.RLock()
defer r.mu.RUnlock()
total := r.stats.Hits + r.stats.Misses
hitRatio := float64(0)
if total > 0 {
hitRatio = float64(r.stats.Hits) / float64(total)
}
// 获取Redis信息
info, _ := r.client.Info(context.Background(), "memory", "keyspace").Result()
keysCount := r.parseKeysCount(info)
return &LevelCacheStats{
Hits: r.stats.Hits,
Misses: r.stats.Misses,
Sets: r.stats.Sets,
Deletes: r.stats.Deletes,
HitRatio: hitRatio,
Size: keysCount,
MaxSize: 0, // Redis没有硬限制
}
}
// 解析键数量
func (r *RedisCache) parseKeysCount(info string) int64 {
lines := strings.Split(info, "\r\n")
for _, line := range lines {
if strings.HasPrefix(line, "db") {
parts := strings.Split(line, ":")
if len(parts) == 2 {
keys := strings.Split(parts[1], ",")
for _, key := range keys {
if strings.HasPrefix(key, "keys=") {
count, _ := strconv.ParseInt(strings.TrimPrefix(key, "keys="), 10, 64)
return count
}
}
}
}
}
return 0
}
// 获取内存使用情况
func (r *RedisCache) GetMemoryUsage() (int64, error) {
info, err := r.client.Info(context.Background(), "memory").Result()
if err != nil {
return 0, err
}
return r.parseMemoryUsage(info), nil
}
// 解析内存使用
func (r *RedisCache) parseMemoryUsage(info string) int64 {
lines := strings.Split(info, "\r\n")
for _, line := range lines {
if strings.HasPrefix(line, "used_memory:") {
usage, _ := strconv.ParseInt(strings.TrimPrefix(line, "used_memory:"), 10, 64)
return usage
}
}
return 0
}
// 健康检查
func (r *RedisCache) HealthCheck(ctx context.Context) error {
return r.client.Ping(ctx).Err()
}
// 关闭连接
func (r *RedisCache) Close() error {
if closer, ok := r.client.(redis.Closer); ok {
return closer.Close()
}
return nil
}
// Redis集群缓存
type RedisClusterCache struct {
*RedisCache
client *redis.ClusterClient
}
// 创建Redis集群缓存
func NewRedisClusterCache(config *RedisCacheConfig) (*RedisClusterCache, error) {
if !config.EnableCluster {
return nil, fmt.Errorf("cluster not enabled in config")
}
baseCache, err := NewRedisCache(config)
if err != nil {
return nil, err
}
client := baseCache.client.(*redis.ClusterClient)
return &RedisClusterCache{
RedisCache: baseCache,
client: client,
}, nil
}
// 获取集群节点信息
func (r *RedisClusterCache) GetClusterInfo(ctx context.Context) ([]redis.ClusterSlot, error) {
return r.client.ClusterSlots(ctx).Result()
}
// 缓存指标接口
type CacheMetrics interface {
recordLatency(operation string, duration time.Duration)
getLatencyStats() map[string]*LatencyStats
}
// 延迟统计
type LatencyStats struct {
Count int64 `json:"count"`
Sum time.Duration `json:"sum"`
Min time.Duration `json:"min"`
Max time.Duration `json:"max"`
Avg time.Duration `json:"avg"`
P95 time.Duration `json:"p95"`
P99 time.Duration `json:"p99"`
}
// 简单的指标实现
type SimpleCacheMetrics struct {
mu sync.RWMutex
latency map[string]*LatencyStats
}
func NewCacheMetrics() *SimpleCacheMetrics {
return &SimpleCacheMetrics{
latency: make(map[string]*LatencyStats),
}
}
func (m *SimpleCacheMetrics) recordLatency(operation string, duration time.Duration) {
m.mu.Lock()
defer m.mu.Unlock()
stats, exists := m.latency[operation]
if !exists {
stats = &LatencyStats{
Min: duration,
Max: duration,
}
m.latency[operation] = stats
}
stats.Count++
stats.Sum += duration
if duration < stats.Min {
stats.Min = duration
}
if duration > stats.Max {
stats.Max = duration
}
stats.Avg = time.Duration(int64(stats.Sum) / stats.Count)
// 简化处理，P95和P99需要更复杂的统计
stats.P95 = stats.Avg * 120 / 100
stats.P99 = stats.Avg * 150 / 100
}
func (m *SimpleCacheMetrics) getLatencyStats() map[string]*LatencyStats {
m.mu.RLock()
defer m.mu.RUnlock()
result := make(map[string]*LatencyStats)
for op, stats := range m.latency {
result[op] = &LatencyStats{
Count: stats.Count,
Sum: stats.Sum,
Min: stats.Min,
Max: stats.Max,
Avg: stats.Avg,
P95: stats.P95,
P99: stats.P99,
}
}
return result
}
---
5.6 数据库事务管理
01.事务基础概念
a.ACID特性
a.原子性（Atomicity）
事务中的所有操作要么全部执行，要么全部不执行。
b.一致性（Consistency）
事务执行后，数据库状态从一个一致性状态转换到另一个一致性状态。
c.隔离性（Isolation）
多个并发事务之间互不干扰。
d.持久性（Durability）
事务一旦提交，其结果就是永久性的。
e.事务特性说明
---
// transaction/properties.go
package transaction
import (
"context"
"errors"
"fmt"
"sync"
"time"
)
// 事务隔离级别
type IsolationLevel int
const (
IsolationLevelReadUncommitted IsolationLevel = iota // 读未提交
IsolationLevelReadCommitted // 读已提交
IsolationLevelRepeatableRead // 可重复读
IsolationLevelSerializable // 串行化
)
// 事务传播行为
type PropagationBehavior int
const (
PropagationRequired PropagationBehavior = iota // 必需事务
PropagationRequiresNew // 新建事务
PropagationSupports // 支持事务
PropagationNotSupported // 不支持事务
PropagationNever // 从不使用事务
PropagationNested // 嵌套事务
)
// 事务状态
type TransactionStatus int
const (
TransactionStatusActive TransactionStatus = iota // 活跃
TransactionStatusCommitted // 已提交
TransactionStatusRolledBack // 已回滚
TransactionStatusUnknown // 未知状态
)
// 事务配置
type TransactionConfig struct {
Isolation IsolationLevel `yaml:"isolation"` // 隔离级别
Propagation PropagationBehavior `yaml:"propagation"` // 传播行为
ReadOnly bool `yaml:"read_only"` // 只读事务
Timeout time.Duration `yaml:"timeout"` // 超时时间
Name string `yaml:"name"` // 事务名称
RollbackFor []error `yaml:"rollback_for"` // 回滚异常
NoRollbackFor []error `yaml:"no_rollback_for"` // 不回滚异常
}
// 默认事务配置
func DefaultTransactionConfig() *TransactionConfig {
return &TransactionConfig{
Isolation: IsolationLevelReadCommitted,
Propagation: PropagationRequired,
ReadOnly: false,
Timeout: 30 * time.Second,
Name: "default",
}
}
// 事务错误定义
var (
ErrTransactionNotFound = errors.New("transaction not found")
ErrTransactionActive = errors.New("transaction is still active")
ErrTransactionCompleted = errors.New("transaction has been completed")
ErrTransactionRolledBack = errors.New("transaction has been rolled back")
ErrTransactionTimeout = errors.New("transaction timeout")
ErrTransactionNested = errors.New("nested transaction not supported")
ErrInvalidIsolationLevel = errors.New("invalid isolation level")
ErrInvalidPropagation = errors.New("invalid propagation behavior")
)
// 事务接口
type Transaction interface {
// 基本信息
GetID() string
GetName() string
GetStatus() TransactionStatus
GetConfig() *TransactionConfig
// 事务操作
Commit() error
Rollback() error
Savepoint(name string) (Savepoint, error)
RollbackToSavepoint(savepoint Savepoint) error
ReleaseSavepoint(savepoint Savepoint) error
// 状态检查
IsActive() bool
IsCompleted() bool
IsRollbackOnly() bool
SetRollbackOnly()
// 上下文
Context() context.Context
// 时间信息
GetCreateTime() time.Time
GetCommitTime() *time.Time
GetRollbackTime() *time.Time
GetDuration() time.Duration
}
// 保存点接口
type Savepoint interface {
GetName() string
GetTransaction() Transaction
GetCreateTime() time.Time
}
// 事务管理器接口
type TransactionManager interface {
// 事务管理
Begin(ctx context.Context, config *TransactionConfig) (Transaction, error)
Commit(tx Transaction) error
Rollback(tx Transaction) error
// 便捷方法
Execute(ctx context.Context, config *TransactionConfig, fn func(ctx context.Context, tx Transaction) error) error
ExecuteRequired(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error
ExecuteRequiresNew(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error
// 事务状态
GetTransaction(ctx context.Context) (Transaction, bool)
SetTransaction(ctx context.Context, tx Transaction) context.Context
ClearTransaction(ctx context.Context) context.Context
// 统计信息
GetStats() *TransactionStats
}
// 事务统计信息
type TransactionStats struct {
TotalTransactions int64 `json:"total_transactions"`
ActiveTransactions int64 `json:"active_transactions"`
CommittedTransactions int64 `json:"committed_transactions"`
RolledBackTransactions int64 `json:"rolled_back_transactions"`
AvgCommitTime time.Duration `json:"avg_commit_time"`
AvgRollbackTime time.Duration `json:"avg_rollback_time"`
MaxCommitTime time.Duration `json:"max_commit_time"`
MaxRollbackTime time.Duration `json:"max_rollback_time"`
TimeoutCount int64 `json:"timeout_count"`
ErrorCount int64 `json:"error_count"`
}
// 事务监听器接口
type TransactionListener interface {
OnBegin(tx Transaction)
OnCommit(tx Transaction)
OnRollback(tx Transaction, err error)
OnCompletion(tx Transaction)
OnError(tx Transaction, err error)
}
// 事务事件类型
type TransactionEventType int
const (
TransactionEventBegin TransactionEventType = iota
TransactionEventCommit
TransactionEventRollback
TransactionEventCompletion
TransactionEventError
)
// 事务事件
type TransactionEvent struct {
Type TransactionEventType
Tx Transaction
Error error
Context context.Context
}
// 事务监听器管理
type TransactionListenerManager struct {
listeners []TransactionListener
mu sync.RWMutex
}
func NewTransactionListenerManager() *TransactionListenerManager {
return &TransactionListenerManager{
listeners: make([]TransactionListener, 0),
}
}
func (m *TransactionListenerManager) AddListener(listener TransactionListener) {
m.mu.Lock()
defer m.mu.Unlock()
m.listeners = append(m.listeners, listener)
}
func (m *TransactionListenerManager) RemoveListener(listener TransactionListener) {
m.mu.Lock()
defer m.mu.Unlock()
for i, l := range m.listeners {
if l == listener {
m.listeners = append(m.listeners[:i], m.listeners[i+1:]...)
break
}
}
}
func (m *TransactionListenerManager) NotifyEvent(event *TransactionEvent) {
m.mu.RLock()
listeners := make([]TransactionListener, len(m.listeners))
copy(listeners, m.listeners)
m.mu.RUnlock()
for _, listener := range listeners {
switch event.Type {
case TransactionEventBegin:
listener.OnBegin(event.Tx)
case TransactionEventCommit:
listener.OnCommit(event.Tx)
case TransactionEventRollback:
listener.OnRollback(event.Tx, event.Error)
case TransactionEventCompletion:
listener.OnCompletion(event.Tx)
case TransactionEventError:
listener.OnError(event.Tx, event.Error)
}
}
}
// 隔离级别转换
func (il IsolationLevel) String() string {
switch il {
case IsolationLevelReadUncommitted:
return "READ_UNCOMMITTED"
case IsolationLevelReadCommitted:
return "READ_COMMITTED"
case IsolationLevelRepeatableRead:
return "REPEATABLE_READ"
case IsolationLevelSerializable:
return "SERIALIZABLE"
default:
return "UNKNOWN"
}
}
// 传播行为转换
func (pb PropagationBehavior) String() string {
switch pb {
case PropagationRequired:
return "REQUIRED"
case PropagationRequiresNew:
return "REQUIRES_NEW"
case PropagationSupports:
return "SUPPORTS"
case PropagationNotSupported:
return "NOT_SUPPORTED"
case PropagationNever:
return "NEVER"
case PropagationNested:
return "NESTED"
default:
return "UNKNOWN"
}
}
// 事务状态转换
func (ts TransactionStatus) String() string {
switch ts {
case TransactionStatusActive:
return "ACTIVE"
case TransactionStatusCommitted:
return "COMMITTED"
case TransactionStatusRolledBack:
return "ROLLED_BACK"
case TransactionStatusUnknown:
return "UNKNOWN"
default:
return "UNKNOWN"
}
}
// 检查异常是否应该回滚
func (config *TransactionConfig) ShouldRollback(err error) bool {
// 如果明确指定了不回滚的异常
for _, noRollbackErr := range config.NoRollbackFor {
if errors.Is(err, noRollbackErr) {
return false
}
}
// 如果指定了回滚异常
if len(config.RollbackFor) > 0 {
for _, rollbackErr := range config.RollbackFor {
if errors.Is(err, rollbackErr) {
return true
}
}
return false
}
// 默认情况下，所有错误都回滚
return true
}
// 事务上下文键
type transactionContextKey struct{}
// 从上下文获取事务
func GetTransactionFromContext(ctx context.Context) (Transaction, bool) {
tx, ok := ctx.Value(transactionContextKey{}).(Transaction)
return tx, ok
}
// 设置事务到上下文
func SetTransactionToContext(ctx context.Context, tx Transaction) context.Context {
return context.WithValue(ctx, transactionContextKey{}, tx)
}
// 从上下文清除事务
func ClearTransactionFromContext(ctx context.Context) context.Context {
return context.WithValue(ctx, transactionContextKey{}, nil)
}
---
b.GORM事务实现
a.基础事务
使用GORM的基础事务功能。
b.嵌套事务
支持嵌套事务和保存点。
c.分布式事务
跨多个数据库的事务处理。
d.GORM事务示例
---
// transaction/gorm_transaction.go
package transaction
import (
"context"
"database/sql"
"fmt"
"sync"
"time"
"gorm.io/gorm"
)
// GORM事务实现
type GormTransaction struct {
id string
name string
config *TransactionConfig
db *gorm.DB
status TransactionStatus
rollbackOnly bool
createTime time.Time
commitTime *time.Time
rollbackTime *time.Time
savepoints map[string]*GormSavepoint
mu sync.RWMutex
listeners []TransactionListener
}
// 创建GORM事务
func NewGormTransaction(db *gorm.DB, config *TransactionConfig) *GormTransaction {
if config == nil {
config = DefaultTransactionConfig()
}
return &GormTransaction{
id: generateTransactionID(),
name: config.Name,
config: config,
db: db,
status: TransactionStatusActive,
createTime: time.Now(),
savepoints: make(map[string]*GormSavepoint),
listeners: make([]TransactionListener, 0),
}
}
// 获取事务ID
func (tx *GormTransaction) GetID() string {
return tx.id
}
// 获取事务名称
func (tx *GormTransaction) GetName() string {
return tx.name
}
// 获取事务状态
func (tx *GormTransaction) GetStatus() TransactionStatus {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.status
}
// 获取事务配置
func (tx *GormTransaction) GetConfig() *TransactionConfig {
return tx.config
}
// 提交事务
func (tx *GormTransaction) Commit() error {
tx.mu.Lock()
defer tx.mu.Unlock()
if tx.status != TransactionStatusActive {
return ErrTransactionCompleted
}
start := time.Now()
err := tx.db.Commit().Error
duration := time.Since(start)
if err != nil {
tx.status = TransactionStatusRolledBack
tx.notifyEvent(&TransactionEvent{
Type: TransactionEventRollback,
Tx: tx,
Error: err,
})
return fmt.Errorf("commit failed: %w", err)
}
tx.status = TransactionStatusCommitted
tx.commitTime = &start
tx.notifyEvent(&TransactionEvent{
Type: TransactionEventCommit,
Tx: tx,
})
return nil
}
// 回滚事务
func (tx *GormTransaction) Rollback() error {
tx.mu.Lock()
defer tx.mu.Unlock()
if tx.status != TransactionStatusActive {
return ErrTransactionCompleted
}
start := time.Now()
err := tx.db.Rollback().Error
duration := time.Since(start)
tx.status = TransactionStatusRolledBack
tx.rollbackTime = &start
tx.notifyEvent(&TransactionEvent{
Type: TransactionEventRollback,
Tx: tx,
Error: err,
})
if err != nil {
return fmt.Errorf("rollback failed: %w", err)
}
return nil
}
// 创建保存点
func (tx *GormTransaction) Savepoint(name string) (Savepoint, error) {
tx.mu.Lock()
defer tx.mu.Unlock()
if tx.status != TransactionStatusActive {
return nil, ErrTransactionCompleted
}
if _, exists := tx.savepoints[name]; exists {
return nil, fmt.Errorf("savepoint %s already exists", name)
}
// 执行保存点SQL
savepointSQL := fmt.Sprintf("SAVEPOINT %s", name)
if err := tx.db.Exec(savepointSQL).Error; err != nil {
return nil, fmt.Errorf("create savepoint failed: %w", err)
}
savepoint := &GormSavepoint{
name: name,
transaction: tx,
createTime: time.Now(),
}
tx.savepoints[name] = savepoint
return savepoint, nil
}
// 回滚到保存点
func (tx *GormTransaction) RollbackToSavepoint(savepoint Savepoint) error {
tx.mu.Lock()
defer tx.mu.Unlock()
if tx.status != TransactionStatusActive {
return ErrTransactionCompleted
}
gormSavepoint, ok := savepoint.(*GormSavepoint)
if !ok {
return fmt.Errorf("invalid savepoint type")
}
if gormSavepoint.transaction != tx {
return fmt.Errorf("savepoint does not belong to this transaction")
}
// 执行回滚到保存点SQL
rollbackSQL := fmt.Sprintf("ROLLBACK TO SAVEPOINT %s", gormSavepoint.name)
if err := tx.db.Exec(rollbackSQL).Error; err != nil {
return fmt.Errorf("rollback to savepoint failed: %w", err)
}
// 删除该保存点之后的所有保存点
for name, sp := range tx.savepoints {
if sp.createTime.After(gormSavepoint.createTime) {
delete(tx.savepoints, name)
}
}
return nil
}
// 释放保存点
func (tx *GormTransaction) ReleaseSavepoint(savepoint Savepoint) error {
tx.mu.Lock()
defer tx.mu.Unlock()
if tx.status != TransactionStatusActive {
return ErrTransactionCompleted
}
gormSavepoint, ok := savepoint.(*GormSavepoint)
if !ok {
return fmt.Errorf("invalid savepoint type")
}
if gormSavepoint.transaction != tx {
return fmt.Errorf("savepoint does not belong to this transaction")
}
// 执行释放保存点SQL
releaseSQL := fmt.Sprintf("RELEASE SAVEPOINT %s", gormSavepoint.name)
if err := tx.db.Exec(releaseSQL).Error; err != nil {
return fmt.Errorf("release savepoint failed: %w", err)
}
// 从保存点列表中移除
delete(tx.savepoints, gormSavepoint.name)
return nil
}
// 检查事务是否活跃
func (tx *GormTransaction) IsActive() bool {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.status == TransactionStatusActive
}
// 检查事务是否完成
func (tx *GormTransaction) IsCompleted() bool {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.status != TransactionStatusActive
}
// 检查是否只能回滚
func (tx *GormTransaction) IsRollbackOnly() bool {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.rollbackOnly
}
// 设置只能回滚
func (tx *GormTransaction) SetRollbackOnly() {
tx.mu.Lock()
defer tx.mu.Unlock()
tx.rollbackOnly = true
}
// 获取上下文
func (tx *GormTransaction) Context() context.Context {
return SetTransactionToContext(context.Background(), tx)
}
// 获取创建时间
func (tx *GormTransaction) GetCreateTime() time.Time {
return tx.createTime
}
// 获取提交时间
func (tx *GormTransaction) GetCommitTime() *time.Time {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.commitTime
}
// 获取回滚时间
func (tx *GormTransaction) GetRollbackTime() *time.Time {
tx.mu.RLock()
defer tx.mu.RUnlock()
return tx.rollbackTime
}
// 获取持续时间
func (tx *GormTransaction) GetDuration() time.Duration {
tx.mu.RLock()
defer tx.mu.RUnlock()
endTime := time.Now()
if tx.commitTime != nil {
endTime = *tx.commitTime
} else if tx.rollbackTime != nil {
endTime = *tx.rollbackTime
}
return endTime.Sub(tx.createTime)
}
// 添加监听器
func (tx *GormTransaction) AddListener(listener TransactionListener) {
tx.mu.Lock()
defer tx.mu.Unlock()
tx.listeners = append(tx.listeners, listener)
}
// 移除监听器
func (tx *GormTransaction) RemoveListener(listener TransactionListener) {
tx.mu.Lock()
defer tx.mu.Unlock()
for i, l := range tx.listeners {
if l == listener {
tx.listeners = append(tx.listeners[:i], tx.listeners[i+1:]...)
break
}
}
}
// 通知事件
func (tx *GormTransaction) notifyEvent(event *TransactionEvent) {
for _, listener := range tx.listeners {
switch event.Type {
case TransactionEventBegin:
listener.OnBegin(event.Tx)
case TransactionEventCommit:
listener.OnCommit(event.Tx)
case TransactionEventRollback:
listener.OnRollback(event.Tx, event.Error)
case TransactionEventCompletion:
listener.OnCompletion(event.Tx)
case TransactionEventError:
listener.OnError(event.Tx, event.Error)
}
}
}
// 获取事务统计
func (tx *GormTransaction) GetStats() map[string]interface{} {
tx.mu.RLock()
defer tx.mu.RUnlock()
return map[string]interface{}{
"id": tx.id,
"name": tx.name,
"status": tx.status.String(),
"rollback_only": tx.rollbackOnly,
"create_time": tx.createTime,
"duration": tx.GetDuration(),
"savepoints": len(tx.savepoints),
}
}
// GORM保存点实现
type GormSavepoint struct {
name string
transaction *GormTransaction
createTime time.Time
}
func (sp *GormSavepoint) GetName() string {
return sp.name
}
func (sp *GormSavepoint) GetTransaction() Transaction {
return sp.transaction
}
func (sp *GormSavepoint) GetCreateTime() time.Time {
return sp.createTime
}
// GORM事务管理器
type GormTransactionManager struct {
db *gorm.DB
config *TransactionConfig
stats *TransactionStats
listeners []TransactionListener
mu sync.RWMutex
}
// 创建GORM事务管理器
func NewGormTransactionManager(db *gorm.DB, config *TransactionConfig) *GormTransactionManager {
if config == nil {
config = DefaultTransactionConfig()
}
return &GormTransactionManager{
db: db,
config: config,
stats: &TransactionStats{},
listeners: make([]TransactionListener, 0),
}
}
// 开始事务
func (tm *GormTransactionManager) Begin(ctx context.Context, config *TransactionConfig) (Transaction, error) {
if config == nil {
config = tm.config
}
// 检查传播行为
switch config.Propagation {
case PropagationRequired:
if existingTx, exists := tm.GetTransaction(ctx); exists {
return existingTx, nil
}
case PropagationRequiresNew:
// 总是创建新事务
case PropagationSupports:
if existingTx, exists := tm.GetTransaction(ctx); exists {
return existingTx, nil
}
// 如果没有现有事务，不创建事务
return &NonTransaction{}, nil
case PropagationNotSupported:
if existingTx, exists := tm.GetTransaction(ctx); exists {
// 挂起现有事务
ctx = ClearTransactionFromContext(ctx)
}
return &NonTransaction{}, nil
case PropagationNever:
if _, exists := tm.GetTransaction(ctx); exists {
return nil, fmt.Errorf("existing transaction found for propagation never")
}
return &NonTransaction{}, nil
case PropagationNested:
// 嵌套事务（使用保存点）
if existingTx, exists := tm.GetTransaction(ctx); exists {
savepointName := fmt.Sprintf("nested_%s", generateTransactionID())
savepoint, err := existingTx.Savepoint(savepointName)
if err != nil {
return nil, fmt.Errorf("create nested transaction failed: %w", err)
}
return &NestedTransaction{
savepoint: savepoint,
parent: existingTx,
}, nil
}
}
// 创建新事务
txDB := tm.db.Begin()
if txDB.Error != nil {
return nil, fmt.Errorf("begin transaction failed: %w", txDB.Error)
}
// 设置隔离级别
if config.Isolation != IsolationLevelReadCommitted {
if err := tm.setIsolationLevel(txDB, config.Isolation); err != nil {
txDB.Rollback()
return nil, fmt.Errorf("set isolation level failed: %w", err)
}
}
// 设置只读
if config.ReadOnly {
if err := txDB.Exec("SET TRANSACTION READ ONLY").Error; err != nil {
txDB.Rollback()
return nil, fmt.Errorf("set read only failed: %w", err)
}
}
transaction := NewGormTransaction(txDB, config)
// 设置超时
if config.Timeout > 0 {
go func() {
time.Sleep(config.Timeout)
if transaction.IsActive() {
transaction.SetRollbackOnly()
tm.notifyEvent(&TransactionEvent{
Type: TransactionEventError,
Tx: transaction,
Error: ErrTransactionTimeout,
})
}
}()
}
// 更新统计
tm.updateStats(func(stats *TransactionStats) {
stats.TotalTransactions++
stats.ActiveTransactions++
})
// 通知事件
tm.notifyEvent(&TransactionEvent{
Type: TransactionEventBegin,
Tx: transaction,
Context: ctx,
})
return transaction, nil
}
// 提交事务
func (tm *GormTransactionManager) Commit(tx Transaction) error {
err := tx.Commit()
// 更新统计
if err != nil {
tm.updateStats(func(stats *TransactionStats) {
stats.ActiveTransactions--
stats.RolledBackTransactions++
stats.ErrorCount++
})
} else {
tm.updateStats(func(stats *TransactionStats) {
stats.ActiveTransactions--
stats.CommittedTransactions++
duration := tx.GetDuration()
if duration > stats.MaxCommitTime {
stats.MaxCommitTime = duration
}
totalCommitTime := stats.AvgCommitTime * time.Duration(stats.CommittedTransactions-1)
stats.AvgCommitTime = (totalCommitTime + duration) / time.Duration(stats.CommittedTransactions)
})
}
// 通知事件
tm.notifyEvent(&TransactionEvent{
Type: TransactionEventCompletion,
Tx: tx,
})
return err
}
// 回滚事务
func (tm *GormTransactionManager) Rollback(tx Transaction) error {
err := tx.Rollback()
// 更新统计
tm.updateStats(func(stats *TransactionStats) {
stats.ActiveTransactions--
stats.RolledBackTransactions++
if err != nil {
stats.ErrorCount++
}
duration := tx.GetDuration()
if duration > stats.MaxRollbackTime {
stats.MaxRollbackTime = duration
}
totalRollbackTime := stats.AvgRollbackTime * time.Duration(stats.RolledBackTransactions-1)
stats.AvgRollbackTime = (totalRollbackTime + duration) / time.Duration(stats.RolledBackTransactions)
})
// 通知事件
tm.notifyEvent(&TransactionEvent{
Type: TransactionEventRollback,
Tx: tx,
Error: err,
})
return err
}
// 执行事务
func (tm *GormTransactionManager) Execute(ctx context.Context, config *TransactionConfig, fn func(ctx context.Context, tx Transaction) error) error {
tx, err := tm.Begin(ctx, config)
if err != nil {
return err
}
defer func() {
if p := recover(); p != nil {
if err := tm.Rollback(tx); err != nil {
// 记录回滚失败错误
}
panic(p)
}
}()
// 将事务设置到上下文中
ctx = tm.SetTransaction(ctx, tx)
// 执行业务逻辑
err = fn(ctx, tx)
if err != nil {
// 检查是否应该回滚
if config != nil && config.ShouldRollback(err) {
if rollbackErr := tm.Rollback(tx); rollbackErr != nil {
return fmt.Errorf("business error: %v, rollback error: %w", err, rollbackErr)
}
return err
}
}
// 检查事务是否被标记为回滚
if tx.IsRollbackOnly() {
return tm.Rollback(tx)
}
return tm.Commit(tx)
}
// 执行必需事务
func (tm *GormTransactionManager) ExecuteRequired(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error {
return tm.Execute(ctx, &TransactionConfig{
Propagation: PropagationRequired,
}, fn)
}
// 执行新事务
func (tm *GormTransactionManager) ExecuteRequiresNew(ctx context.Context, fn func(ctx context.Context, tx Transaction) error) error {
return tm.Execute(ctx, &TransactionConfig{
Propagation: PropagationRequiresNew,
}, fn)
}
// 获取事务
func (tm *GormTransactionManager) GetTransaction(ctx context.Context) (Transaction, bool) {
return GetTransactionFromContext(ctx)
}
// 设置事务
func (tm *GormTransactionManager) SetTransaction(ctx context.Context, tx Transaction) context.Context {
return SetTransactionToContext(ctx, tx)
}
// 清除事务
func (tm *GormTransactionManager) ClearTransaction(ctx context.Context) context.Context {
return ClearTransactionFromContext(ctx)
}
// 获取统计信息
func (tm *GormTransactionManager) GetStats() *TransactionStats {
tm.mu.RLock()
defer tm.mu.RUnlock()
return tm.stats
}
// 设置隔离级别
func (tm *GormTransactionManager) setIsolationLevel(db *gorm.DB, level IsolationLevel) error {
var isolation string
switch level {
case IsolationLevelReadUncommitted:
isolation = "READ UNCOMMITTED"
case IsolationLevelReadCommitted:
isolation = "READ COMMITTED"
case IsolationLevelRepeatableRead:
isolation = "REPEATABLE READ"
case IsolationLevelSerializable:
isolation = "SERIALIZABLE"
default:
return ErrInvalidIsolationLevel
}
return db.Exec(fmt.Sprintf("SET TRANSACTION ISOLATION LEVEL %s", isolation)).Error
}
// 添加监听器
func (tm *GormTransactionManager) AddListener(listener TransactionListener) {
tm.mu.Lock()
defer tm.mu.Unlock()
tm.listeners = append(tm.listeners, listener)
}
// 移除监听器
func (tm *GormTransactionManager) RemoveListener(listener TransactionListener) {
tm.mu.Lock()
defer tm.mu.Unlock()
for i, l := range tm.listeners {
if l == listener {
tm.listeners = append(tm.listeners[:i], tm.listeners[i+1:]...)
break
}
}
}
// 通知事件
func (tm *GormTransactionManager) notifyEvent(event *TransactionEvent) {
tm.mu.RLock()
listeners := make([]TransactionListener, len(tm.listeners))
copy(listeners, tm.listeners)
tm.mu.RUnlock()
for _, listener := range listeners {
switch event.Type {
case TransactionEventBegin:
listener.OnBegin(event.Tx)
case TransactionEventCommit:
listener.OnCommit(event.Tx)
case TransactionEventRollback:
listener.OnRollback(event.Tx, event.Error)
case TransactionEventCompletion:
listener.OnCompletion(event.Tx)
case TransactionEventError:
listener.OnError(event.Tx, event.Error)
}
}
}
// 更新统计信息
func (tm *GormTransactionManager) updateStats(updateFunc func(*TransactionStats)) {
tm.mu.Lock()
defer tm.mu.Unlock()
updateFunc(tm.stats)
}
// 生成事务ID
func generateTransactionID() string {
return fmt.Sprintf("tx_%d_%d", time.Now().UnixNano(), time.Now().Unix())
}
// 非事务实现
type NonTransaction struct{}
func (tx *NonTransaction) GetID() string { return "non_transaction" }
func (tx *NonTransaction) GetName() string { return "Non Transaction" }
func (tx *NonTransaction) GetStatus() TransactionStatus { return TransactionStatusUnknown }
func (tx *NonTransaction) GetConfig() *TransactionConfig { return nil }
func (tx *NonTransaction) Commit() error { return nil }
func (tx *NonTransaction) Rollback() error { return nil }
func (tx *NonTransaction) Savepoint(name string) (Savepoint, error) { return nil, ErrTransactionNested }
func (tx *NonTransaction) RollbackToSavepoint(savepoint Savepoint) error { return ErrTransactionNested }
func (tx *NonTransaction) ReleaseSavepoint(savepoint Savepoint) error { return ErrTransactionNested }
func (tx *NonTransaction) IsActive() bool { return false }
func (tx *NonTransaction) IsCompleted() bool { return true }
func (tx *NonTransaction) IsRollbackOnly() bool { return false }
func (tx *NonTransaction) SetRollbackOnly() {}
func (tx *NonTransaction) Context() context.Context { return context.Background() }
func (tx *NonTransaction) GetCreateTime() time.Time { return time.Now() }
func (tx *NonTransaction) GetCommitTime() *time.Time { return nil }
func (tx *NonTransaction) GetRollbackTime() *time.Time { return nil }
func (tx *NonTransaction) GetDuration() time.Duration { return 0 }
// 嵌套事务实现
type NestedTransaction struct {
savepoint Savepoint
parent Transaction
}
func (tx *NestedTransaction) GetID() string { return tx.savepoint.GetName() }
func (tx *NestedTransaction) GetName() string { return fmt.Sprintf("Nested: %s", tx.savepoint.GetName()) }
func (tx *NestedTransaction) GetStatus() TransactionStatus { return tx.parent.GetStatus() }
func (tx *NestedTransaction) GetConfig() *TransactionConfig { return tx.parent.GetConfig() }
func (tx *NestedTransaction) Commit() error {
return tx.parent.ReleaseSavepoint(tx.savepoint)
}
func (tx *NestedTransaction) Rollback() error {
return tx.parent.RollbackToSavepoint(tx.savepoint)
}
func (tx *NestedTransaction) Savepoint(name string) (Savepoint, error) { return tx.parent.Savepoint(name) }
func (tx *NestedTransaction) RollbackToSavepoint(savepoint Savepoint) error {
return tx.parent.RollbackToSavepoint(savepoint)
}
func (tx *NestedTransaction) ReleaseSavepoint(savepoint Savepoint) error {
return tx.parent.ReleaseSavepoint(savepoint)
}
func (tx *NestedTransaction) IsActive() bool { return tx.savepoint.GetTransaction().IsActive() }
func (tx *NestedTransaction) IsCompleted() bool { return false }
func (tx *NestedTransaction) IsRollbackOnly() bool { return tx.parent.IsRollbackOnly() }
func (tx *NestedTransaction) SetRollbackOnly() { tx.parent.SetRollbackOnly() }
func (tx *NestedTransaction) Context() context.Context { return tx.parent.Context() }
func (tx *NestedTransaction) GetCreateTime() time.Time { return tx.savepoint.GetCreateTime() }
func (tx *NestedTransaction) GetCommitTime() *time.Time { return nil }
func (tx *NestedTransaction) GetRollbackTime() *time.Time { return nil }
func (tx *NestedTransaction) GetDuration() time.Duration { return time.Since(tx.savepoint.GetCreateTime()) }
---
5.7 数据验证与转换
01.数据验证架构
a.验证器接口
a.统一验证接口
定义通用的数据验证接口。
b.验证规则
支持多种验证规则和自定义规则。
c.错误处理
统一的验证错误处理机制。
d.验证器接口示例
---
// validation/interface.go
package validation
import (
"context"
"fmt"
"reflect"
"strings"
)
// 验证器接口
type Validator interface {
Validate(ctx context.Context, obj interface{}) error
ValidateField(ctx context.Context, field interface{}, rules ...Rule) error
ValidateStruct(ctx context.Context, obj interface{}) error
ValidateMap(ctx context.Context, data map[string]interface{}) error
}
// 验证规则接口
type Rule interface {
Name() string
Validate(ctx context.Context, value interface{}) error
GetMessage() string
WithMessage(message string) Rule
}
// 验证错误
type ValidationError struct {
Field string `json:"field"`
Rule string `json:"rule"`
Message string `json:"message"`
Value interface{} `json:"value"`
}
func (e *ValidationError) Error() string {
if e.Field != "" {
return fmt.Sprintf("field '%s' validation failed: %s", e.Field, e.Message)
}
return e.Message
}
// 验证错误集合
type ValidationErrors struct {
Errors []*ValidationError `json:"errors"`
}
func (e *ValidationErrors) Error() string {
var messages []string
for _, err := range e.Errors {
messages = append(messages, err.Error())
}
return strings.Join(messages, "; ")
}
func (e *ValidationErrors) Add(err *ValidationError) {
e.Errors = append(e.Errors, err)
}
func (e *ValidationErrors) HasErrors() bool {
return len(e.Errors) > 0
}
// 验证上下文
type ValidationContext struct {
Context context.Context
Object interface{}
Field string
Rules []Rule
Errors *ValidationErrors
Options *ValidationOptions
}
// 验证选项
type ValidationOptions struct {
SkipEmpty bool `yaml:"skip_empty"` // 跳过空值
SkipNil bool `yaml:"skip_nil"` // 跳过nil值
TrimStrings bool `yaml:"trim_strings"` // 字符串去空格
ConvertTypes bool `yaml:"convert_types"` // 自动类型转换
ValidateNested bool `yaml:"validate_nested"` // 验证嵌套结构
FieldNameCase FieldNameCase `yaml:"field_name_case"` // 字段名大小写
Locale string `yaml:"locale"` // 本地化
}
// 字段名大小写
type FieldNameCase int
const (
FieldNameCaseOriginal FieldNameCase = iota // 保持原样
FieldNameCaseSnake // 转为蛇形
FieldNameCaseCamel // 转为驼峰
FieldNameCaseKebab // 转为短横线
)
// 默认验证选项
func DefaultValidationOptions() *ValidationOptions {
return &ValidationOptions{
SkipEmpty: false,
SkipNil: false,
TrimStrings: true,
ConvertTypes: false,
ValidateNested: true,
FieldNameCase: FieldNameCaseOriginal,
Locale: "en",
}
}
// 验证器注册表
type ValidatorRegistry struct {
validators map[string]Validator
rules map[string]Rule
messages map[string]map[string]string
mu sync.RWMutex
}
// 创建验证器注册表
func NewValidatorRegistry() *ValidatorRegistry {
return &ValidatorRegistry{
validators: make(map[string]Validator),
rules: make(map[string]Rule),
messages: make(map[string]map[string]string),
}
}
// 注册验证器
func (r *ValidatorRegistry) RegisterValidator(name string, validator Validator) {
r.mu.Lock()
defer r.mu.Unlock()
r.validators[name] = validator
}
// 注册验证规则
func (r *ValidatorRegistry) RegisterRule(name string, rule Rule) {
r.mu.Lock()
defer r.mu.Unlock()
r.rules[name] = rule
}
// 注册验证消息
func (r *ValidatorRegistry) RegisterMessages(locale string, messages map[string]string) {
r.mu.Lock()
defer r.mu.Unlock()
r.messages[locale] = messages
}
// 获取验证器
func (r *ValidatorRegistry) GetValidator(name string) (Validator, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
validator, exists := r.validators[name]
return validator, exists
}
// 获取验证规则
func (r *ValidatorRegistry) GetRule(name string) (Rule, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
rule, exists := r.rules[name]
return rule, exists
}
// 获取验证消息
func (r *ValidatorRegistry) GetMessage(locale, ruleName string) (string, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
if localeMessages, exists := r.messages[locale]; exists {
if message, exists := localeMessages[ruleName]; exists {
return message, true
}
}
// 回退到默认语言
if enMessages, exists := r.messages["en"]; exists {
if message, exists := enMessages[ruleName]; exists {
return message, true
}
}
return "", false
}
// 内置验证规则
var BuiltInRules = map[string]Rule{
"required": &RequiredRule{},
"email": &EmailRule{},
"phone": &PhoneRule{},
"url": &URLRule{},
"uuid": &UUIDRule{},
"numeric": &NumericRule{},
"alpha": &AlphaRule{},
"alphanum": &AlphaNumRule{},
"min": &MinRule{},
"max": &MaxRule{},
"len": &LengthRule{},
"range": &RangeRule{},
"in": &InRule{},
"not_in": &NotInRule{},
"regex": &RegexRule{},
"date": &DateRule{},
"time": &TimeRule{},
}
// 验证规则注册表
var GlobalRuleRegistry = NewValidatorRegistry()
func init() {
// 注册内置规则
for name, rule := range BuiltInRules {
GlobalRuleRegistry.RegisterRule(name, rule)
}
// 注册默认消息
GlobalRuleRegistry.RegisterMessages("en", map[string]string{
"required": "This field is required",
"email": "Must be a valid email address",
"phone": "Must be a valid phone number",
"url": "Must be a valid URL",
"uuid": "Must be a valid UUID",
"numeric": "Must be a numeric value",
"alpha": "Must contain only alphabetic characters",
"alphanum": "Must contain only alphanumeric characters",
"min": "Must be at least %v",
"max": "Must be at most %v",
"len": "Length must be %v",
"range": "Must be between %v and %v",
"in": "Must be one of: %v",
"not_in": "Must not be one of: %v",
"regex": "Must match pattern: %v",
"date": "Must be a valid date",
"time": "Must be a valid time",
})
// 中文消息
GlobalRuleRegistry.RegisterMessages("zh", map[string]string{
"required": "此字段为必填项",
"email": "必须是有效的邮箱地址",
"phone": "必须是有效的电话号码",
"url": "必须是有效的URL",
"uuid": "必须是有效的UUID",
"numeric": "必须是数字",
"alpha": "只能包含字母",
"alphanum": "只能包含字母和数字",
"min": "必须至少为 %v",
"max": "必须至多为 %v",
"len": "长度必须为 %v",
"range": "必须在 %v 和 %v 之间",
"in": "必须是以下值之一: %v",
"not_in": "不能是以下值之一: %v",
"regex": "必须匹配模式: %v",
"date": "必须是有效的日期",
"time": "必须是有效的时间",
})
}
---
b.验证规则实现
a.基础验证规则
实现常用的验证规则。
b.自定义规则
支持自定义验证规则。
c.复合规则
支持规则组合和条件验证。
d.验证规则示例
---
// validation/rules.go
package validation
import (
"context"
"fmt"
"net"
"net/mail"
"net/url"
"regexp"
"strconv"
"strings"
"time"
"unicode"
"github.com/google/uuid"
)
// 必填规则
type RequiredRule struct {
message string
}
func (r *RequiredRule) Name() string {
return "required"
}
func (r *RequiredRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
// 检查字符串
if str, ok := value.(string); ok && strings.TrimSpace(str) == "" {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
// 检查切片
if slice, ok := value.([]interface{}); ok && len(slice) == 0 {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
// 使用反射检查零值
v := reflect.ValueOf(value)
switch v.Kind() {
case reflect.Ptr, reflect.Interface:
if v.IsNil() {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
case reflect.Slice, reflect.Array, reflect.Map, reflect.Chan:
if v.Len() == 0 {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
}
return nil
}
func (r *RequiredRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "This field is required"
}
func (r *RequiredRule) WithMessage(message string) Rule {
return &RequiredRule{message: message}
}
// 邮箱规则
type EmailRule struct {
message string
}
func (r *EmailRule) Name() string {
return "email"
}
func (r *EmailRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
str, ok := value.(string)
if !ok {
return &ValidationError{
Rule: r.Name(),
Message: "Must be a string",
Value: value,
}
}
if str == "" {
return nil
}
_, err := mail.ParseAddress(str)
if err != nil {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
return nil
}
func (r *EmailRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Must be a valid email address"
}
func (r *EmailRule) WithMessage(message string) Rule {
return &EmailRule{message: message}
}
// 手机号规则
type PhoneRule struct {
message string
pattern string
}
func NewPhoneRule(pattern string) *PhoneRule {
return &PhoneRule{
pattern: pattern,
}
}
func (r *PhoneRule) Name() string {
return "phone"
}
func (r *PhoneRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
str, ok := value.(string)
if !ok {
return &ValidationError{
Rule: r.Name(),
Message: "Must be a string",
Value: value,
}
}
if str == "" {
return nil
}
pattern := r.pattern
if pattern == "" {
// 默认中国大陆手机号正则
pattern = `^1[3-9]\d{9}$`
}
matched, err := regexp.MatchString(pattern, str)
if err != nil {
return fmt.Errorf("invalid phone pattern: %w", err)
}
if !matched {
return &ValidationError{
Rule: r.Name(),
Message: r.getMessage(),
Value: value,
}
}
return nil
}
func (r *PhoneRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Must be a valid phone number"
}
func (r *PhoneRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 最小值规则
type MinRule struct {
min float64
message string
}
func NewMinRule(min float64) *MinRule {
return &MinRule{min: min}
}
func (r *MinRule) Name() string {
return "min"
}
func (r *MinRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
var num float64
var err error
switch v := value.(type) {
case int:
num = float64(v)
case int8:
num = float64(v)
case int16:
num = float64(v)
case int32:
num = float64(v)
case int64:
num = float64(v)
case uint:
num = float64(v)
case uint8:
num = float64(v)
case uint16:
num = float64(v)
case uint32:
num = float64(v)
case uint64:
num = float64(v)
case float32:
num = float64(v)
case float64:
num = v
case string:
num, err = strconv.ParseFloat(v, 64)
if err != nil {
return &ValidationError{
Rule: r.Name(),
Message: "Must be a number",
Value: value,
}
}
default:
return &ValidationError{
Rule: r.Name(),
Message: "Unsupported type for numeric validation",
Value: value,
}
}
if num < r.min {
return &ValidationError{
Rule: r.Name(),
Message: fmt.Sprintf(r.getMessage(), r.min),
Value: value,
}
}
return nil
}
func (r *MinRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Must be at least %v"
}
func (r *MinRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 字符串长度规则
type LengthRule struct {
length int
message string
}
func NewLengthRule(length int) *LengthRule {
return &LengthRule{length: length}
}
func (r *LengthRule) Name() string {
return "len"
}
func (r *LengthRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
var length int
switch v := value.(type) {
case string:
length = len(v)
case []interface{}:
length = len(v)
case []string:
length = len(v)
case map[string]interface{}:
length = len(v)
default:
// 使用反射获取长度
val := reflect.ValueOf(value)
switch val.Kind() {
case reflect.Slice, reflect.Array, reflect.Map:
length = val.Len()
default:
return &ValidationError{
Rule: r.Name(),
Message: "Value must have a length",
Value: value,
}
}
}
if length != r.length {
return &ValidationError{
Rule: r.Name(),
Message: fmt.Sprintf(r.getMessage(), r.length),
Value: value,
}
}
return nil
}
func (r *LengthRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Length must be %v"
}
func (r *LengthRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 范围规则
type RangeRule struct {
min float64
max float64
message string
}
func NewRangeRule(min, max float64) *RangeRule {
return &RangeRule{min: min, max: max}
}
func (r *RangeRule) Name() string {
return "range"
}
func (r *RangeRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
var num float64
var err error
switch v := value.(type) {
case int:
num = float64(v)
case float64:
num = v
case string:
num, err = strconv.ParseFloat(v, 64)
if err != nil {
return &ValidationError{
Rule: r.Name(),
Message: "Must be a number",
Value: value,
}
}
default:
return &ValidationError{
Rule: r.Name(),
Message: "Unsupported type for range validation",
Value: value,
}
}
if num < r.min || num > r.max {
return &ValidationError{
Rule: r.Name(),
Message: fmt.Sprintf(r.getMessage(), r.min, r.max),
Value: value,
}
}
return nil
}
func (r *RangeRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Must be between %v and %v"
}
func (r *RangeRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 正则表达式规则
type RegexRule struct {
pattern string
message string
}
func NewRegexRule(pattern string) *RegexRule {
return &RegexRule{pattern: pattern}
}
func (r *RegexRule) Name() string {
return "regex"
}
func (r *RegexRule) Validate(ctx context.Context, value interface{}) error {
if value == nil {
return nil
}
str, ok := value.(string)
if !ok {
return &ValidationError{
Rule: r.Name(),
Message: "Must be a string",
Value: value,
}
}
matched, err := regexp.MatchString(r.pattern, str)
if err != nil {
return fmt.Errorf("invalid regex pattern: %w", err)
}
if !matched {
return &ValidationError{
Rule: r.Name(),
Message: fmt.Sprintf(r.getMessage(), r.pattern),
Value: value,
}
}
return nil
}
func (r *RegexRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Must match pattern: %v"
}
func (r *RegexRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 自定义规则函数
type CustomRule struct {
name string
fn func(ctx context.Context, value interface{}) error
message string
}
func NewCustomRule(name string, fn func(ctx context.Context, value interface{}) error) *CustomRule {
return &CustomRule{
name: name,
fn: fn,
}
}
func (r *CustomRule) Name() string {
return r.name
}
func (r *CustomRule) Validate(ctx context.Context, value interface{}) error {
return r.fn(ctx, value)
}
func (r *CustomRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Validation failed"
}
func (r *CustomRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 条件规则
type ConditionalRule struct {
condition func(value interface{}) bool
rule Rule
}
func NewConditionalRule(condition func(value interface{}) bool, rule Rule) *ConditionalRule {
return &ConditionalRule{
condition: condition,
rule: rule,
}
}
func (r *ConditionalRule) Name() string {
return "conditional"
}
func (r *ConditionalRule) Validate(ctx context.Context, value interface{}) error {
if r.condition(value) {
return r.rule.Validate(ctx, value)
}
return nil
}
func (r *ConditionalRule) GetMessage() string {
return r.rule.GetMessage()
}
func (r *ConditionalRule) WithMessage(message string) Rule {
return &ConditionalRule{
condition: r.condition,
rule: r.rule.WithMessage(message),
}
}
// 复合规则
type CompositeRule struct {
name string
rules []Rule
message string
mode CompositeMode
}
type CompositeMode int
const (
CompositeModeAnd CompositeMode = iota // 所有规则都必须通过
CompositeModeOr // 至少一个规则通过
)
func NewCompositeRule(name string, mode CompositeMode, rules ...Rule) *CompositeRule {
return &CompositeRule{
name: name,
rules: rules,
mode: mode,
}
}
func (r *CompositeRule) Name() string {
return r.name
}
func (r *CompositeRule) Validate(ctx context.Context, value interface{}) error {
var errors []*ValidationError
for _, rule := range r.rules {
err := rule.Validate(ctx, value)
if err != nil {
if validationErr, ok := err.(*ValidationError); ok {
errors = append(errors, validationErr)
} else {
errors = append(errors, &ValidationError{
Rule: rule.Name(),
Message: err.Error(),
Value: value,
})
}
// OR模式：如果有一个成功就通过
if r.mode == CompositeModeOr {
continue
}
} else {
// AND模式：如果失败就返回错误
if r.mode == CompositeModeAnd {
continue
}
// OR模式：如果有一个成功就返回成功
return nil
}
}
// AND模式：所有规则都失败
if r.mode == CompositeModeAnd && len(errors) > 0 {
return &ValidationError{
Rule: r.name,
Message: r.getMessage(),
Value: value,
}
}
// OR模式：所有规则都失败
if r.mode == CompositeModeOr && len(errors) > 0 {
return &ValidationError{
Rule: r.name,
Message: r.getMessage(),
Value: value,
}
}
return nil
}
func (r *CompositeRule) GetMessage() string {
if r.message != "" {
return r.message
}
if msg, exists := GlobalRuleRegistry.GetMessage("en", r.Name()); exists {
return msg
}
return "Validation failed"
}
func (r *CompositeRule) WithMessage(message string) Rule {
newRule := *r
newRule.message = message
return &newRule
}
// 便捷函数
func Required() Rule {
return &RequiredRule{}
}
func Email() Rule {
return &EmailRule{}
}
func Phone(pattern string) Rule {
return NewPhoneRule(pattern)
}
func Min(min float64) Rule {
return NewMinRule(min)
}
func Max(max float64) Rule {
return NewMinRule(max).(*MinRule) // 简化实现
}
func Length(length int) Rule {
return NewLengthRule(length)
}
func Range(min, max float64) Rule {
return NewRangeRule(min, max)
}
func Regex(pattern string) Rule {
return NewRegexRule(pattern)
}
func Custom(name string, fn func(ctx context.Context, value interface{}) error) Rule {
return NewCustomRule(name, fn)
}
func If(condition func(value interface{}) bool, rule Rule) Rule {
return NewConditionalRule(condition, rule)
}
func All(rules ...Rule) Rule {
return NewCompositeRule("all", CompositeModeAnd, rules...)
}
func Any(rules ...Rule) Rule {
return NewCompositeRule("any", CompositeModeOr, rules...)
}
---
c.数据转换器
a.类型转换
支持各种数据类型之间的转换。
b.格式转换
支持日期、时间等格式转换。
c.数据清理
数据清理和标准化。
d.数据转换器示例
---
// validation/converter.go
package validation
import (
"context"
"fmt"
"reflect"
"strconv"
"strings"
"time"
)
// 数据转换器接口
type Converter interface {
Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error)
CanConvert(value interface{}, targetType reflect.Type) bool
}
// 转换器注册表
type ConverterRegistry struct {
converters map[reflect.Type]map[reflect.Type]Converter
mu sync.RWMutex
}
func NewConverterRegistry() *ConverterRegistry {
return &ConverterRegistry{
converters: make(map[reflect.Type]map[reflect.Type]Converter),
}
}
func (r *ConverterRegistry) RegisterConverter(sourceType, targetType reflect.Type, converter Converter) {
r.mu.Lock()
defer r.mu.Unlock()
if _, exists := r.converters[sourceType]; !exists {
r.converters[sourceType] = make(map[reflect.Type]Converter)
}
r.converters[sourceType][targetType] = converter
}
func (r *ConverterRegistry) GetConverter(sourceType, targetType reflect.Type) (Converter, bool) {
r.mu.RLock()
defer r.mu.RUnlock()
if targetConverters, exists := r.converters[sourceType]; exists {
if converter, exists := targetConverters[targetType]; exists {
return converter, true
}
}
return nil, false
}
func (r *ConverterRegistry) Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
if value == nil {
return reflect.Zero(targetType).Interface(), nil
}
sourceType := reflect.TypeOf(value)
// 如果类型匹配，直接返回
if sourceType == targetType {
return value, nil
}
// 尝试直接转换
if sourceType.ConvertibleTo(targetType) {
sourceValue := reflect.ValueOf(value)
targetValue := sourceValue.Convert(targetType)
return targetValue.Interface(), nil
}
// 查找注册的转换器
if converter, exists := r.GetConverter(sourceType, targetType); exists {
return converter.Convert(ctx, value, targetType)
}
// 默认转换逻辑
return r.defaultConvert(ctx, value, targetType)
}
func (r *ConverterRegistry) defaultConvert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
sourceValue := reflect.ValueOf(value)
targetValue := reflect.Zero(targetType)
switch targetType.Kind() {
case reflect.String:
return fmt.Sprintf("%v", value), nil
case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
if targetType == reflect.TypeOf(time.Time{}) {
// 时间类型特殊处理
return r.convertToTime(value)
}
return r.convertToInt(value, targetType)
case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
return r.convertToUint(value, targetType)
case reflect.Float32, reflect.Float64:
return r.convertToFloat(value, targetType)
case reflect.Bool:
return r.convertToBool(value)
case reflect.Slice:
return r.convertToSlice(value, targetType)
case reflect.Map:
return r.convertToMap(value, targetType)
case reflect.Ptr:
return r.convertToPointer(ctx, value, targetType)
case reflect.Struct:
return r.convertToStruct(ctx, value, targetType)
default:
return nil, fmt.Errorf("unsupported conversion from %v to %v", sourceValue.Type(), targetType)
}
}
// 字符串转整数
func (r *ConverterRegistry) convertToInt(value interface{}, targetType reflect.Type) (interface{}, error) {
var intVal int64
var err error
switch v := value.(type) {
case string:
intVal, err = strconv.ParseInt(strings.TrimSpace(v), 10, 64)
case float64:
intVal = int64(v)
case int:
intVal = int64(v)
case int64:
intVal = v
case bool:
if v {
intVal = 1
} else {
intVal = 0
}
default:
return nil, fmt.Errorf("cannot convert %v to int", reflect.TypeOf(value))
}
if err != nil {
return nil, fmt.Errorf("invalid integer format: %w", err)
}
result := reflect.New(targetType).Elem()
result.SetInt(intVal)
return result.Interface(), nil
}
// 字符串转无符号整数
func (r *ConverterRegistry) convertToUint(value interface{}, targetType reflect.Type) (interface{}, error) {
var uintVal uint64
var err error
switch v := value.(type) {
case string:
uintVal, err = strconv.ParseUint(strings.TrimSpace(v), 10, 64)
case float64:
uintVal = uint64(v)
case int:
uintVal = uint64(v)
case int64:
uintVal = uint64(v)
case uint64:
uintVal = v
case bool:
if v {
uintVal = 1
} else {
uintVal = 0
}
default:
return nil, fmt.Errorf("cannot convert %v to uint", reflect.TypeOf(value))
}
if err != nil {
return nil, fmt.Errorf("invalid unsigned integer format: %w", err)
}
result := reflect.New(targetType).Elem()
result.SetUint(uintVal)
return result.Interface(), nil
}
// 字符串转浮点数
func (r *ConverterRegistry) convertToFloat(value interface{}, targetType reflect.Type) (interface{}, error) {
var floatVal float64
var err error
switch v := value.(type) {
case string:
floatVal, err = strconv.ParseFloat(strings.TrimSpace(v), 64)
case int:
floatVal = float64(v)
case int64:
floatVal = float64(v)
case uint64:
floatVal = float64(v)
case float64:
floatVal = v
case bool:
if v {
floatVal = 1.0
} else {
floatVal = 0.0
}
default:
return nil, fmt.Errorf("cannot convert %v to float", reflect.TypeOf(value))
}
if err != nil {
return nil, fmt.Errorf("invalid float format: %w", err)
}
result := reflect.New(targetType).Elem()
result.SetFloat(floatVal)
return result.Interface(), nil
}
// 字符串转布尔值
func (r *ConverterRegistry) convertToBool(value interface{}) (interface{}, error) {
switch v := value.(type) {
case string:
str := strings.ToLower(strings.TrimSpace(v))
switch str {
case "true", "1", "yes", "on", "enabled":
return true, nil
case "false", "0", "no", "off", "disabled":
return false, nil
default:
return false, fmt.Errorf("invalid boolean format: %s", str)
}
case int:
return v != 0, nil
case int64:
return v != 0, nil
case float64:
return v != 0.0, nil
case bool:
return v, nil
default:
return false, fmt.Errorf("cannot convert %v to bool", reflect.TypeOf(value))
}
}
// 字符串转时间
func (r *ConverterRegistry) convertToTime(value interface{}) (interface{}, error) {
switch v := value.(type) {
case string:
// 尝试多种时间格式
formats := []string{
time.RFC3339,
"2006-01-02 15:04:05",
"2006-01-02",
"15:04:05",
time.RFC3339Nano,
}
for _, format := range formats {
if t, err := time.Parse(format, v); err == nil {
return t, nil
}
}
return nil, fmt.Errorf("invalid time format: %s", v)
case int64:
return time.Unix(v, 0), nil
case float64:
sec := int64(v)
nsec := int64((v - float64(sec)) * 1e9)
return time.Unix(sec, nsec), nil
case time.Time:
return v, nil
default:
return nil, fmt.Errorf("cannot convert %v to time", reflect.TypeOf(value))
}
}
// 转换为切片
func (r *ConverterRegistry) convertToSlice(value interface{}, targetType reflect.Type) (interface{}, error) {
sourceValue := reflect.ValueOf(value)
targetSlice := reflect.MakeSlice(targetType, 0, sourceValue.Len())
for i := 0; i < sourceValue.Len(); i++ {
element := sourceValue.Index(i).Interface()
convertedElement, err := r.Convert(context.Background(), element, targetType.Elem())
if err != nil {
return nil, fmt.Errorf("failed to convert slice element at index %d: %w", i, err)
}
targetSlice = reflect.Append(targetSlice, reflect.ValueOf(convertedElement))
}
return targetSlice.Interface(), nil
}
// 转换为Map
func (r *ConverterRegistry) convertToMap(value interface{}, targetType reflect.Type) (interface{}, error) {
sourceValue := reflect.ValueOf(value)
targetMap := reflect.MakeMap(targetType)
iter := sourceValue.MapRange()
for iter.Next() {
key := iter.Key().Interface()
val := iter.Value().Interface()
convertedKey, err := r.Convert(context.Background(), key, targetType.Key())
if err != nil {
return nil, fmt.Errorf("failed to convert map key: %w", err)
}
convertedVal, err := r.Convert(context.Background(), val, targetType.Elem())
if err != nil {
return nil, fmt.Errorf("failed to convert map value: %w", err)
}
targetMap.SetMapIndex(reflect.ValueOf(convertedKey), reflect.ValueOf(convertedVal))
}
return targetMap.Interface(), nil
}
// 转换为指针
func (r *ConverterRegistry) convertToPointer(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
if value == nil {
return reflect.Zero(targetType).Interface(), nil
}
convertedValue, err := r.Convert(ctx, value, targetType.Elem())
if err != nil {
return nil, err
}
targetPointer := reflect.New(targetType.Elem())
targetPointer.Elem().Set(reflect.ValueOf(convertedValue))
return targetPointer.Interface(), nil
}
// 转换为结构体
func (r *ConverterRegistry) convertToStruct(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
sourceValue := reflect.ValueOf(value)
targetStruct := reflect.New(targetType).Elem()
if sourceValue.Kind() == reflect.Map {
return r.convertMapToStruct(ctx, sourceValue, targetStruct)
} else if sourceValue.Kind() == reflect.Struct {
return r.convertStructToStruct(ctx, sourceValue, targetStruct)
}
return nil, fmt.Errorf("cannot convert %v to struct", sourceValue.Kind())
}
// Map转结构体
func (r *ConverterRegistry) convertMapToStruct(ctx context.Context, mapValue reflect.Value, targetStruct reflect.Value) (interface{}, error) {
mapType := mapValue.Type()
if mapType.Key().Kind() != reflect.String {
return nil, fmt.Errorf("map key must be string for struct conversion")
}
for i := 0; i < targetStruct.NumField(); i++ {
field := targetStruct.Type().Field(i)
fieldValue := targetStruct.Field(i)
if !fieldValue.CanSet() {
continue
}
// 获取字段名（支持json标签）
fieldName := field.Name
if jsonTag := field.Tag.Get("json"); jsonTag != "" {
parts := strings.Split(jsonTag, ",")
if parts[0] != "" && parts[0] != "-" {
fieldName = parts[0]
}
}
// 从map中获取值
mapKey := reflect.ValueOf(fieldName)
mapVal := mapValue.MapIndex(mapKey)
if !mapVal.IsValid() {
continue
}
// 转换值
convertedValue, err := r.Convert(ctx, mapVal.Interface(), field.Type)
if err != nil {
return nil, fmt.Errorf("failed to convert field %s: %w", fieldName, err)
}
fieldValue.Set(reflect.ValueOf(convertedValue))
}
return targetStruct.Interface(), nil
}
// 结构体转结构体
func (r *ConverterRegistry) convertStructToStruct(ctx context.Context, sourceStruct, targetStruct reflect.Value) (interface{}, error) {
sourceType := sourceStruct.Type()
for i := 0; i < targetStruct.NumField(); i++ {
targetField := targetStruct.Type().Field(i)
targetFieldValue := targetStruct.Field(i)
if !targetFieldValue.CanSet() {
continue
}
// 在源结构体中查找同名字段
sourceField, found := sourceType.FieldByName(targetField.Name)
if !found {
continue
}
sourceFieldValue := sourceStruct.FieldByName(sourceField.Name)
if !sourceFieldValue.IsValid() || sourceFieldValue.IsZero() {
continue
}
// 转换值
convertedValue, err := r.Convert(ctx, sourceFieldValue.Interface(), targetField.Type)
if err != nil {
return nil, fmt.Errorf("failed to convert field %s: %w", targetField.Name, err)
}
targetFieldValue.Set(reflect.ValueOf(convertedValue))
}
return targetStruct.Interface(), nil
}
// 默认转换器注册表
var DefaultConverterRegistry = NewConverterRegistry()
func init() {
// 注册常用转换器
// 字符串到各种类型的转换器
stringType := reflect.TypeOf("")
intType := reflect.TypeOf(0)
floatType := reflect.TypeOf(0.0)
boolType := reflect.TypeOf(false)
timeType := reflect.TypeOf(time.Time{})
DefaultConverterRegistry.RegisterConverter(stringType, intType, &StringToIntConverter{})
DefaultConverterRegistry.RegisterConverter(stringType, floatType, &StringToFloatConverter{})
DefaultConverterRegistry.RegisterConverter(stringType, boolType, &StringToBoolConverter{})
DefaultConverterRegistry.RegisterConverter(stringType, timeType, &StringToTimeConverter{})
}
// 字符串转整数转换器
type StringToIntConverter struct{}
func (c *StringToIntConverter) Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
str, ok := value.(string)
if !ok {
return nil, fmt.Errorf("expected string, got %T", value)
}
intVal, err := strconv.ParseInt(strings.TrimSpace(str), 10, 64)
if err != nil {
return nil, fmt.Errorf("invalid integer format: %w", err)
}
result := reflect.New(targetType).Elem()
result.SetInt(intVal)
return result.Interface(), nil
}
func (c *StringToIntConverter) CanConvert(value interface{}, targetType reflect.Type) bool {
_, ok := value.(string)
return ok && (targetType.Kind() == reflect.Int || targetType.Kind() == reflect.Int64)
}
// 字符串转浮点数转换器
type StringToFloatConverter struct{}
func (c *StringToFloatConverter) Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
str, ok := value.(string)
if !ok {
return nil, fmt.Errorf("expected string, got %T", value)
}
floatVal, err := strconv.ParseFloat(strings.TrimSpace(str), 64)
if err != nil {
return nil, fmt.Errorf("invalid float format: %w", err)
}
result := reflect.New(targetType).Elem()
result.SetFloat(floatVal)
return result.Interface(), nil
}
func (c *StringToFloatConverter) CanConvert(value interface{}, targetType reflect.Type) bool {
_, ok := value.(string)
return ok && (targetType.Kind() == reflect.Float32 || targetType.Kind() == reflect.Float64)
}
// 字符串转布尔值转换器
type StringToBoolConverter struct{}
func (c *StringToBoolConverter) Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
str, ok := value.(string)
if !ok {
return nil, fmt.Errorf("expected string, got %T", value)
}
switch strings.ToLower(strings.TrimSpace(str)) {
case "true", "1", "yes", "on", "enabled":
return true, nil
case "false", "0", "no", "off", "disabled":
return false, nil
default:
return false, fmt.Errorf("invalid boolean format: %s", str)
}
}
func (c *StringToBoolConverter) CanConvert(value interface{}, targetType reflect.Type) bool {
_, ok := value.(string)
return ok && targetType.Kind() == reflect.Bool
}
// 字符串转时间转换器
type StringToTimeConverter struct{}
func (c *StringToTimeConverter) Convert(ctx context.Context, value interface{}, targetType reflect.Type) (interface{}, error) {
str, ok := value.(string)
if !ok {
return nil, fmt.Errorf("expected string, got %T", value)
}
if targetType != reflect.TypeOf(time.Time{}) {
return nil, fmt.Errorf("target type must be time.Time")
}
formats := []string{
time.RFC3339,
"2006-01-02 15:04:05",
"2006-01-02",
"15:04:05",
time.RFC3339Nano,
}
for _, format := range formats {
if t, err := time.Parse(format, str); err == nil {
return t, nil
}
}
return nil, fmt.Errorf("invalid time format: %s", str)
}
func (c *StringToTimeConverter) CanConvert(value interface{}, targetType reflect.Type) bool {
_, ok := value.(string)
return ok && targetType == reflect.TypeOf(time.Time{})
}
---
5.8 读写分离与分库分表
01.读写分离架构
a.主从复制
a.主库写操作
所有写操作在主库执行。
b.从库读操作
读操作分发到从库。
c.数据同步
主从数据同步机制。
d.读写分离示例
---
// sharding/read_write_splitting.go
package sharding
import (
"context"
"database/sql"
"errors"
"fmt"
"math/rand"
"sync"
"sync/atomic"
"time"
"gorm.io/gorm"
)
// 数据库类型
type DatabaseType int
const (
DatabaseTypeMaster DatabaseType = iota // 主库
DatabaseTypeSlave // 从库
)
// 负载均衡策略
type LoadBalanceStrategy int
const (
LoadBalanceStrategyRoundRobin LoadBalanceStrategy = iota // 轮询
LoadBalanceStrategyRandom // 随机
LoadBalanceStrategyLeastConnections // 最少连接
LoadBalanceStrategyWeighted // 加权
LoadBalanceStrategyConsistentHash // 一致性哈希
)
// 读写分离配置
type ReadWriteSplittingConfig struct {
Master *DatabaseConfig `yaml:"master"` // 主库配置
Slaves []*DatabaseConfig `yaml:"slaves"` // 从库配置列表
Strategy LoadBalanceStrategy `yaml:"strategy"` // 负载均衡策略
Weights []int `yaml:"weights"` // 权重配置
Timeout time.Duration `yaml:"timeout"` // 读写分离超时
MaxRetries int `yaml:"max_retries"` // 最大重试次数
EnableFailover bool `yaml:"enable_failover"` // 启用故障转移
HealthCheckInterval time.Duration `yaml:"health_check_interval"` // 健康检查间隔
PreferSlave bool `yaml:"prefer_slave"` // 优先使用从库
ForceMasterQueries []string `yaml:"force_master_queries"` // 强制主库查询
}
// 数据库连接
type DatabaseConnection struct {
Type DatabaseType
Config *DatabaseConfig
DB *gorm.DB
SQL *sql.DB
IsHealthy bool
Weight int
Connections int64 // 当前连接数
LastUsed time.Time
mu sync.RWMutex
}
// 读写分离器
type ReadWriteSplitting struct {
master *DatabaseConnection
slaves []*DatabaseConnection
config *ReadWriteSplittingConfig
stats *ReadWriteSplittingStats
mu sync.RWMutex
currentIndex int64 // 轮询索引
healthTicker *time.Ticker
stopChan chan struct{}
}
// 读写分离统计
type ReadWriteSplittingStats struct {
MasterQueries int64 `json:"master_queries"`
SlaveQueries int64 `json:"slave_queries"`
TotalQueries int64 `json:"total_queries"`
FailoverCount int64 `json:"failover_count"`
ErrorCount int64 `json:"error_count"`
ResponseTime time.Duration `json:"avg_response_time"`
SlaveHitRatio float64 `json:"slave_hit_ratio"`
}
// 创建读写分离器
func NewReadWriteSplitting(config *ReadWriteSplittingConfig) (*ReadWriteSplitting, error) {
if config == nil {
return nil, errors.New("config is required")
}
splitter := &ReadWriteSplitting{
config: config,
stats: &ReadWriteSplittingStats{},
currentIndex: 0,
stopChan: make(chan struct{}),
}
// 初始化主库连接
if err := splitter.initMaster(); err != nil {
return nil, fmt.Errorf("failed to init master: %w", err)
}
// 初始化从库连接
if err := splitter.initSlaves(); err != nil {
return nil, fmt.Errorf("failed to init slaves: %w", err)
}
// 启动健康检查
if config.HealthCheckInterval > 0 {
splitter.startHealthCheck()
}
return splitter, nil
}
// 初始化主库
func (rw *ReadWriteSplitting) initMaster() error {
conn, err := rw.createConnection(rw.config.Master, DatabaseTypeMaster, 1)
if err != nil {
return err
}
rw.master = conn
return nil
}
// 初始化从库
func (rw *ReadWriteSplitting) initSlaves() error {
for i, slaveConfig := range rw.config.Slaves {
weight := 1
if len(rw.config.Weights) > i {
weight = rw.config.Weights[i]
}
conn, err := rw.createConnection(slaveConfig, DatabaseTypeSlave, weight)
if err != nil {
return fmt.Errorf("failed to create slave connection %d: %w", i, err)
}
rw.slaves = append(rw.slaves, conn)
}
return nil
}
// 创建数据库连接
func (rw *ReadWriteSplitting) createConnection(config *DatabaseConfig, dbType DatabaseType, weight int) (*DatabaseConnection, error) {
// 创建GORM连接
db, err := NewGORMFromConfig(config)
if err != nil {
return nil, err
}
// 获取底层SQL连接
sqlDB, err := db.DB()
if err != nil {
return nil, err
}
conn := &DatabaseConnection{
Type: dbType,
Config: config,
DB: db,
SQL: sqlDB,
IsHealthy: true,
Weight: weight,
LastUsed: time.Now(),
}
return conn, nil
}
// 获取主库连接
func (rw *ReadWriteSplitting) Master() *DatabaseConnection {
rw.mu.RLock()
defer rw.mu.RUnlock()
atomic.AddInt64(&rw.stats.MasterQueries, 1)
atomic.AddInt64(&rw.stats.TotalQueries, 1)
rw.master.LastUsed = time.Now()
atomic.AddInt64(&rw.master.Connections, 1)
return rw.master
}
// 获取从库连接
func (rw *ReadWriteSplitting) Slave() *DatabaseConnection {
rw.mu.RLock()
defer rw.mu.RUnlock()
if len(rw.slaves) == 0 {
// 没有从库，使用主库
atomic.AddInt64(&rw.stats.MasterQueries, 1)
atomic.AddInt64(&rw.stats.TotalQueries, 1)
rw.master.LastUsed = time.Now()
atomic.AddInt64(&rw.master.Connections, 1)
return rw.master
}
// 选择健康的从库
slave := rw.selectHealthySlave()
if slave == nil {
if rw.config.EnableFailover {
// 故障转移到主库
atomic.AddInt64(&rw.stats.FailoverCount, 1)
atomic.AddInt64(&rw.stats.MasterQueries, 1)
atomic.AddInt64(&rw.stats.TotalQueries, 1)
rw.master.LastUsed = time.Now()
atomic.AddInt64(&rw.master.Connections, 1)
return rw.master
}
return nil
}
atomic.AddInt64(&rw.stats.SlaveQueries, 1)
atomic.AddInt64(&rw.stats.TotalQueries, 1)
slave.LastUsed = time.Now()
atomic.AddInt64(&slave.Connections, 1)
return slave
}
// 选择健康的从库
func (rw *ReadWriteSplitting) selectHealthySlave() *DatabaseConnection {
healthySlaves := make([]*DatabaseConnection, 0)
for _, slave := range rw.slaves {
slave.mu.RLock()
if slave.IsHealthy {
healthySlaves = append(healthySlaves, slave)
}
slave.mu.RUnlock()
}
if len(healthySlaves) == 0 {
return nil
}
// 根据策略选择从库
switch rw.config.Strategy {
case LoadBalanceStrategyRoundRobin:
return rw.selectByRoundRobin(healthySlaves)
case LoadBalanceStrategyRandom:
return rw.selectByRandom(healthySlaves)
case LoadBalanceStrategyLeastConnections:
return rw.selectByLeastConnections(healthySlaves)
case LoadBalanceStrategyWeighted:
return rw.selectByWeighted(healthySlaves)
case LoadBalanceStrategyConsistentHash:
return rw.selectByConsistentHash(healthySlaves)
default:
return healthySlaves[0]
}
}
// 轮询选择
func (rw *ReadWriteSplitting) selectByRoundRobin(slaves []*DatabaseConnection) *DatabaseConnection {
index := atomic.AddInt64(&rw.currentIndex, 1) - 1
return slaves[int(index)%len(slaves)]
}
// 随机选择
func (rw *ReadWriteSplitting) selectByRandom(slaves []*DatabaseConnection) *DatabaseConnection {
index := rand.Intn(len(slaves))
return slaves[index]
}
// 最少连接选择
func (rw *ReadWriteSplitting) selectByLeastConnections(slaves []*DatabaseConnection) *DatabaseConnection {
var selected *DatabaseConnection
minConnections := int64(^uint64(0) >> 1) // 最大值
for _, slave := range slaves {
connections := atomic.LoadInt64(&slave.Connections)
if connections < minConnections {
minConnections = connections
selected = slave
}
}
return selected
}
// 加权选择
func (rw *ReadWriteSplitting) selectByWeighted(slaves []*DatabaseConnection) *DatabaseConnection {
totalWeight := 0
for _, slave := range slaves {
totalWeight += slave.Weight
}
if totalWeight == 0 {
return slaves[0]
}
randNum := rand.Intn(totalWeight)
currentWeight := 0
for _, slave := range slaves {
currentWeight += slave.Weight
if randNum < currentWeight {
return slave
}
}
return slaves[0]
}
// 一致性哈希选择
func (rw *ReadWriteSplitting) selectByConsistentHash(slaves []*DatabaseConnection) *DatabaseConnection {
// 简化实现，使用随机哈希
hash := rand.Int63()
index := int(hash) % len(slaves)
return slaves[index]
}
// 执行查询
func (rw *ReadWriteSplitting) Query(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error) {
conn := rw.selectReadConnection(query)
if conn == nil {
return nil, errors.New("no available connection")
}
start := time.Now()
defer func() {
atomic.AddInt64(&conn.Connections, -1)
rw.updateResponseTime(time.Since(start))
}()
return conn.SQL.QueryContext(ctx, query, args...)
}
// 执行查询行
func (rw *ReadWriteSplitting) QueryRow(ctx context.Context, query string, args ...interface{}) *sql.Row {
conn := rw.selectReadConnection(query)
if conn == nil {
return nil
}
start := time.Now()
defer func() {
atomic.AddInt64(&conn.Connections, -1)
rw.updateResponseTime(time.Since(start))
}()
return conn.SQL.QueryRowContext(ctx, query, args...)
}
// 执行写操作
func (rw *ReadWriteSplitting) Exec(ctx context.Context, query string, args ...interface{}) (sql.Result, error) {
conn := rw.Master()
if conn == nil {
return nil, errors.New("master connection not available")
}
start := time.Now()
defer func() {
atomic.AddInt64(&conn.Connections, -1)
rw.updateResponseTime(time.Since(start))
}()
return conn.SQL.ExecContext(ctx, query, args...)
}
// 选择读连接
func (rw *ReadWriteSplitting) selectReadConnection(query string) *DatabaseConnection {
// 检查是否强制使用主库
if rw.shouldUseMaster(query) {
return rw.Master()
}
// 根据配置选择连接
if rw.config.PreferSlave {
return rw.Slave()
}
// 默认：写操作用主库，读操作用从库
if rw.isWriteQuery(query) {
return rw.Master()
}
return rw.Slave()
}
// 检查是否应该使用主库
func (rw *ReadWriteSplitting) shouldUseMaster(query string) bool {
queryUpper := strings.ToUpper(strings.TrimSpace(query))
// 检查强制主库查询列表
for _, pattern := range rw.config.ForceMasterQueries {
if strings.Contains(queryUpper, strings.ToUpper(pattern)) {
return true
}
}
return false
}
// 检查是否为写操作
func (rw *ReadWriteSplitting) isWriteQuery(query string) bool {
queryUpper := strings.ToUpper(strings.TrimSpace(query))
writeKeywords := []string{
"INSERT", "UPDATE", "DELETE", "CREATE", "DROP", "ALTER",
"TRUNCATE", "REPLACE", "LOAD DATA", "LOCK TABLES",
}
for _, keyword := range writeKeywords {
if strings.HasPrefix(queryUpper, keyword) {
return true
}
}
return false
}
// 更新响应时间
func (rw *ReadWriteSplitting) updateResponseTime(duration time.Duration) {
atomic.StoreInt64((*int64)(&rw.stats.ResponseTime), int64(duration))
}
// 启动健康检查
func (rw *ReadWriteSplitting) startHealthCheck() {
rw.healthTicker = time.NewTicker(rw.config.HealthCheckInterval)
go func() {
for {
select {
case <-rw.healthTicker.C:
rw.performHealthCheck()
case <-rw.stopChan:
return
}
}
}()
}
// 执行健康检查
func (rw *ReadWriteSplitting) performHealthCheck() {
// 检查主库
rw.checkConnectionHealth(rw.master)
// 检查从库
for _, slave := range rw.slaves {
rw.checkConnectionHealth(slave)
}
// 更新统计
rw.updateStats()
}
// 检查连接健康状态
func (rw *ReadWriteSplitting) checkConnectionHealth(conn *DatabaseConnection) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
err := conn.SQL.PingContext(ctx)
conn.mu.Lock()
conn.IsHealthy = (err == nil)
conn.mu.Unlock()
if err != nil {
atomic.AddInt64(&rw.stats.ErrorCount, 1)
}
}
// 更新统计信息
func (rw *ReadWriteSplitting) updateStats() {
total := atomic.LoadInt64(&rw.stats.TotalQueries)
if total > 0 {
slaveQueries := atomic.LoadInt64(&rw.stats.SlaveQueries)
hitRatio := float64(slaveQueries) / float64(total)
atomic.StoreInt64((*int64)(&rw.stats.SlaveHitRatio), int64(hitRatio*100))
}
}
// 获取统计信息
func (rw *ReadWriteSplitting) GetStats() *ReadWriteSplittingStats {
rw.updateStats()
return &ReadWriteSplittingStats{
MasterQueries: atomic.LoadInt64(&rw.stats.MasterQueries),
SlaveQueries: atomic.LoadInt64(&rw.stats.SlaveQueries),
TotalQueries: atomic.LoadInt64(&rw.stats.TotalQueries),
FailoverCount: atomic.LoadInt64(&rw.stats.FailoverCount),
ErrorCount: atomic.LoadInt64(&rw.stats.ErrorCount),
ResponseTime: time.Duration(atomic.LoadInt64((*int64)(&rw.stats.ResponseTime))),
SlaveHitRatio: float64(atomic.LoadInt64((*int64)(&rw.stats.SlaveHitRatio))) / 100.0,
}
}
// 获取连接信息
func (rw *ReadWriteSplitting) GetConnectionInfo() map[string]interface{} {
rw.mu.RLock()
defer rw.mu.RUnlock()
info := make(map[string]interface{})
// 主库信息
masterInfo := map[string]interface{}{
"type": "master",
"host": rw.master.Config.Host,
"port": rw.master.Config.Port,
"healthy": rw.master.IsHealthy,
"connections": atomic.LoadInt64(&rw.master.Connections),
"last_used": rw.master.LastUsed,
}
info["master"] = masterInfo
// 从库信息
var slavesInfo []map[string]interface{}
for i, slave := range rw.slaves {
slaveInfo := map[string]interface{}{
"index": i,
"type": "slave",
"host": slave.Config.Host,
"port": slave.Config.Port,
"healthy": slave.IsHealthy,
"weight": slave.Weight,
"connections": atomic.LoadInt64(&slave.Connections),
"last_used": slave.LastUsed,
}
slavesInfo = append(slavesInfo, slaveInfo)
}
info["slaves"] = slavesInfo
return info
}
// 关闭连接
func (rw *ReadWriteSplitting) Close() error {
close(rw.stopChan)
if rw.healthTicker != nil {
rw.healthTicker.Stop()
}
var errors []error
// 关闭主库
if rw.master != nil && rw.master.SQL != nil {
if err := rw.master.SQL.Close(); err != nil {
errors = append(errors, fmt.Errorf("failed to close master: %w", err))
}
}
// 关闭从库
for i, slave := range rw.slaves {
if slave != nil && slave.SQL != nil {
if err := slave.SQL.Close(); err != nil {
errors = append(errors, fmt.Errorf("failed to close slave %d: %w", i, err))
}
}
}
if len(errors) > 0 {
return fmt.Errorf("failed to close some connections: %v", errors)
}
return nil
}
---
b.分库分表策略
a.水平分片
按业务规则将数据分散到多个数据库。
b.垂直分片
按业务功能将数据分散到不同的数据库。
c.分片算法
一致性哈希、范围分片、哈希分片等。
d.分片策略示例
---
// sharding/sharding_strategy.go
package sharding
import (
"context"
"fmt"
"hash/crc32"
"strconv"
"strings"
"sync"
"time"
"gorm.io/gorm"
)
// 分片类型
type ShardingType int
const (
ShardingTypeHorizontal ShardingType = iota // 水平分片
ShardingTypeVertical // 垂直分片
)
// 分片算法
type ShardingAlgorithm int
const (
ShardingAlgorithmHash ShardingAlgorithm = iota // 哈希分片
ShardingAlgorithmRange // 范围分片
ShardingAlgorithmConsistentHash // 一致性哈希
ShardingAlgorithmModulo // 取模分片
ShardingAlgorithmDirectory // 目录映射
)
// 分片配置
type ShardingConfig struct {
Type ShardingType `yaml:"type"` // 分片类型
Algorithm ShardingAlgorithm `yaml:"algorithm"` // 分片算法
ShardCount int `yaml:"shard_count"` // 分片数量
TableCount int `yaml:"table_count"` // 每个分片的表数量
Databases []*DatabaseConfig `yaml:"databases"` // 数据库配置
KeyColumns []string `yaml:"key_columns"` // 分片键字段
Weight []int `yaml:"weight"` // 权重配置
RangeRules []*RangeRule `yaml:"range_rules"` // 范围分片规则
Directory map[string]int `yaml:"directory"` // 目录映射
EnableCrossShardQuery bool `yaml:"enable_cross_shard_query"` // 跨分片查询
DefaultShard int `yaml:"default_shard"` // 默认分片
BroadcastTables []string `yaml:"broadcast_tables"` // 广播表
}
// 范围规则
type RangeRule struct {
ShardIndex int `yaml:"shard_index"`
Min interface{} `yaml:"min"`
Max interface{} `yaml:"max"`
TableIndex int `yaml:"table_index"`
}
// 分片键
type ShardingKey struct {
Column string `json:"column"`
Value interface{} `json:"value"`
Type string `json:"type"`
}
// 分片结果
type ShardingResult struct {
ShardIndex int `json:"shard_index"`
TableIndex int `json:"table_index"`
Database string `json:"database"`
Table string `json:"table"`
SQL string `json:"sql"`
Args []interface{} `json:"args"`
}
// 分片器接口
type ShardingStrategy interface {
CalculateShard(key ShardingKey) *ShardingResult
CalculateTable(key ShardingKey) *ShardingResult
GetAllShards() []*ShardingResult
GetBroadcastTables() []string
IsBroadcastTable(table string) bool
}
// 哈希分片策略
type HashShardingStrategy struct {
config *ShardingConfig
mu sync.RWMutex
}
func NewHashShardingStrategy(config *ShardingConfig) *HashShardingStrategy {
return &HashShardingStrategy{
config: config,
}
}
func (s *HashShardingStrategy) CalculateShard(key ShardingKey) *ShardingResult {
// 计算哈希值
hash := s.calculateHash(key.Value)
shardIndex := int(hash) % s.config.ShardCount
tableIndex := int(hash) % s.config.TableCount
database := s.config.Databases[shardIndex].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), tableIndex)
return &ShardingResult{
ShardIndex: shardIndex,
TableIndex: tableIndex,
Database: database,
Table: table,
}
}
func (s *HashShardingStrategy) CalculateTable(key ShardingKey) *ShardingResult {
hash := s.calculateHash(key.Value)
tableIndex := int(hash) % s.config.TableCount
return &ShardingResult{
TableIndex: tableIndex,
Table: fmt.Sprintf("%s_%d", s.getTableName(), tableIndex),
}
}
func (s *HashShardingStrategy) calculateHash(value interface{}) uint32 {
var str string
switch v := value.(type) {
case string:
str = v
case int, int32, int64, uint, uint32, uint64:
str = fmt.Sprintf("%d", v)
default:
str = fmt.Sprintf("%v", v)
}
return crc32.ChecksumIEEE([]byte(str))
}
func (s *HashShardingStrategy) GetAllShards() []*ShardingResult {
var results []*ShardingResult
for i := 0; i < s.config.ShardCount; i++ {
for j := 0; j < s.config.TableCount; j++ {
database := s.config.Databases[i].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), j)
results = append(results, &ShardingResult{
ShardIndex: i,
TableIndex: j,
Database: database,
Table: table,
})
}
}
return results
}
func (s *HashShardingStrategy) GetBroadcastTables() []string {
return s.config.BroadcastTables
}
func (s *HashShardingStrategy) IsBroadcastTable(table string) bool {
for _, broadcastTable := range s.config.BroadcastTables {
if table == broadcastTable {
return true
}
}
return false
}
func (s *HashShardingStrategy) getTableName() string {
// 这里应该从配置或SQL中解析表名
return "table"
}
// 范围分片策略
type RangeShardingStrategy struct {
config *ShardingConfig
rangeRules []*RangeRule
mu sync.RWMutex
}
func NewRangeShardingStrategy(config *ShardingConfig) *RangeShardingStrategy {
return &RangeShardingStrategy{
config: config,
rangeRules: config.RangeRules,
}
}
func (s *RangeShardingStrategy) CalculateShard(key ShardingKey) *ShardingResult {
value := key.Value
shardIndex := s.config.DefaultShard
tableIndex := 0
// 根据范围规则查找分片
for _, rule := range s.rangeRules {
if s.isInRange(value, rule.Min, rule.Max) {
shardIndex = rule.ShardIndex
tableIndex = rule.TableIndex
break
}
}
database := s.config.Databases[shardIndex].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), tableIndex)
return &ShardingResult{
ShardIndex: shardIndex,
TableIndex: tableIndex,
Database: database,
Table: table,
}
}
func (s *RangeShardingStrategy) CalculateTable(key ShardingKey) *ShardingResult {
value := key.Value
tableIndex := 0
for _, rule := range s.rangeRules {
if s.isInRange(value, rule.Min, rule.Max) {
tableIndex = rule.TableIndex
break
}
}
return &ShardingResult{
TableIndex: tableIndex,
Table: fmt.Sprintf("%s_%d", s.getTableName(), tableIndex),
}
}
func (s *RangeShardingStrategy) isInRange(value, min, max interface{}) bool {
// 这里需要根据具体类型实现范围比较
// 简化实现
return true
}
func (s *RangeShardingStrategy) GetAllShards() []*ShardingResult {
var results []*ShardingResult
for i := 0; i < s.config.ShardCount; i++ {
database := s.config.Databases[i].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), i)
results = append(results, &ShardingResult{
ShardIndex: i,
TableIndex: i,
Database: database,
Table: table,
})
}
return results
}
func (s *RangeShardingStrategy) GetBroadcastTables() []string {
return s.config.BroadcastTables
}
func (s *RangeShardingStrategy) IsBroadcastTable(table string) bool {
for _, broadcastTable := range s.config.BroadcastTables {
if table == broadcastTable {
return true
}
}
return false
}
func (s *RangeShardingStrategy) getTableName() string {
return "table"
}
// 一致性哈希分片策略
type ConsistentHashShardingStrategy struct {
config *ShardingConfig
ring *ConsistentHashRing
mu sync.RWMutex
}
type ConsistentHashRing struct {
keys []int
hashMap map[int]string
replicas int
mu sync.RWMutex
}
func NewConsistentHashRing(replicas int) *ConsistentHashRing {
return &ConsistentHashRing{
keys: make([]int, 0),
hashMap: make(map[int]string),
replicas: replicas,
}
}
func (r *ConsistentHashRing) Add(keys ...string) {
r.mu.Lock()
defer r.mu.Unlock()
for _, key := range keys {
for i := 0; i < r.replicas; i++ {
hash := int(crc32.ChecksumIEEE([]byte(strconv.Itoa(i) + key)))
r.keys = append(r.keys, hash)
r.hashMap[hash] = key
}
}
// 排序
for i := 0; i < len(r.keys); i++ {
for j := i + 1; j < len(r.keys); j++ {
if r.keys[i] > r.keys[j] {
r.keys[i], r.keys[j] = r.keys[j], r.keys[i]
}
}
}
}
func (r *ConsistentHashRing) Get(key string) string {
r.mu.RLock()
defer r.mu.RUnlock()
if len(r.keys) == 0 {
return ""
}
hash := int(crc32.ChecksumIEEE([]byte(key)))
// 找到第一个大于等于hash的节点
idx := r.search(hash)
return r.hashMap[r.keys[idx]]
}
func (r *ConsistentHashRing) search(hash int) int {
left, right := 0, len(r.keys)-1
for left <= right {
mid := (left + right) / 2
if r.keys[mid] >= hash {
right = mid - 1
} else {
left = mid + 1
}
}
if left == len(r.keys) {
return 0
}
return left
}
func NewConsistentHashShardingStrategy(config *ShardingConfig) *ConsistentHashShardingStrategy {
ring := NewConsistentHashRing(150) // 虚拟节点数
// 添加分片节点
for i := 0; i < config.ShardCount; i++ {
shardKey := fmt.Sprintf("shard_%d", i)
ring.Add(shardKey)
}
return &ConsistentHashShardingStrategy{
config: config,
ring: ring,
}
}
func (s *ConsistentHashShardingStrategy) CalculateShard(key ShardingKey) *ShardingResult {
keyStr := fmt.Sprintf("%v", key.Value)
shardKey := s.ring.Get(keyStr)
// 从shardKey解析出分片索引
var shardIndex int
_, err := fmt.Sscanf(shardKey, "shard_%d", &shardIndex)
if err != nil {
shardIndex = s.config.DefaultShard
}
tableIndex := shardIndex % s.config.TableCount
database := s.config.Databases[shardIndex].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), tableIndex)
return &ShardingResult{
ShardIndex: shardIndex,
TableIndex: tableIndex,
Database: database,
Table: table,
}
}
func (s *ConsistentHashShardingStrategy) CalculateTable(key ShardingKey) *ShardingResult {
shardResult := s.CalculateShard(key)
return &ShardingResult{
TableIndex: shardResult.TableIndex,
Table: shardResult.Table,
}
}
func (s *ConsistentHashShardingStrategy) GetAllShards() []*ShardingResult {
var results []*ShardingResult
for i := 0; i < s.config.ShardCount; i++ {
for j := 0; j < s.config.TableCount; j++ {
database := s.config.Databases[i].Database
table := fmt.Sprintf("%s_%d", s.getTableName(), j)
results = append(results, &ShardingResult{
ShardIndex: i,
TableIndex: j,
Database: database,
Table: table,
})
}
}
return results
}
func (s *ConsistentHashShardingStrategy) GetBroadcastTables() []string {
return s.config.BroadcastTables
}
func (s *ConsistentHashShardingStrategy) IsBroadcastTable(table string) bool {
for _, broadcastTable := range s.config.BroadcastTables {
if table == broadcastTable {
return true
}
}
return false
}
func (s *ConsistentHashShardingStrategy) getTableName() string {
return "table"
}
// 分片管理器
type ShardingManager struct {
strategy ShardingStrategy
config *ShardingConfig
shards map[string]*DatabaseConnection
mu sync.RWMutex
}
func NewShardingManager(config *ShardingConfig) (*ShardingManager, error) {
var strategy ShardingStrategy
switch config.Algorithm {
case ShardingAlgorithmHash:
strategy = NewHashShardingStrategy(config)
case ShardingAlgorithmRange:
strategy = NewRangeShardingStrategy(config)
case ShardingAlgorithmConsistentHash:
strategy = NewConsistentHashShardingStrategy(config)
default:
return nil, fmt.Errorf("unsupported sharding algorithm: %v", config.Algorithm)
}
manager := &ShardingManager{
strategy: strategy,
config: config,
shards: make(map[string]*DatabaseConnection),
}
// 初始化分片连接
if err := manager.initShards(); err != nil {
return nil, fmt.Errorf("failed to init shards: %w", err)
}
return manager, nil
}
func (m *ShardingManager) initShards() error {
for i, dbConfig := range m.config.Databases {
conn, err := m.createConnection(dbConfig, i)
if err != nil {
return fmt.Errorf("failed to create connection for shard %d: %w", i, err)
}
m.shards[fmt.Sprintf("shard_%d", i)] = conn
}
return nil
}
func (m *ShardingManager) createConnection(config *DatabaseConfig, shardIndex int) (*DatabaseConnection, error) {
db, err := NewGORMFromConfig(config)
if err != nil {
return nil, err
}
sqlDB, err := db.DB()
if err != nil {
return nil, err
}
return &DatabaseConnection{
Type: DatabaseTypeMaster,
Config: config,
DB: db,
SQL: sqlDB,
IsHealthy: true,
}, nil
}
func (m *ShardingManager) GetShard(key ShardingKey) (*DatabaseConnection, error) {
result := m.strategy.CalculateShard(key)
shardKey := fmt.Sprintf("shard_%d", result.ShardIndex)
m.mu.RLock()
conn, exists := m.shards[shardKey]
m.mu.RUnlock()
if !exists {
return nil, fmt.Errorf("shard %s not found", shardKey)
}
return conn, nil
}
func (m *ShardingManager) GetShardingResult(key ShardingKey) *ShardingResult {
return m.strategy.CalculateShard(key)
}
func (m *ShardingManager) IsBroadcastTable(table string) bool {
return m.strategy.IsBroadcastTable(table)
}
func (m *ShardingManager) GetAllShards() []*ShardingResult {
return m.strategy.GetAllShards()
}
func (m *ShardingManager) Close() error {
var errors []error
for key, conn := range m.shards {
if err := conn.SQL.Close(); err != nil {
errors = append(errors, fmt.Errorf("failed to close shard %s: %w", key, err))
}
}
if len(errors) > 0 {
return fmt.Errorf("failed to close some shards: %v", errors)
}
return nil
}
---
6 中间件与插件系统
6.1 汇总：中间件生态
01.中间件分类体系
a.基础设施中间件
a.日志中间件
a.功能说明
统一的请求日志记录和格式化。
b.特性说明
结构化日志、链路追踪集成、可配置日志级别。
c.适用场景
所有服务的日志审计和问题排查。
b.监控中间件
a.功能说明
性能指标收集和监控数据上报。
b.特性说明
请求计数、响应时间、错误率统计。
c.适用场景
服务性能监控和容量规划。
c.链路追踪中间件
a.功能说明
分布式链路追踪和调用链分析。
b.特性说明
Span创建传播、上下文传递、集成Jaeger/Zipkin。
c.适用场景
微服务调用链分析和故障定位。
b.安全相关中间件
a.认证中间件
a.功能说明
用户身份认证和授权验证。
b.特性说明
JWT支持、OAuth2集成、多认证方式。
c.适用场景
API访问控制和用户权限管理。
b.CORS中间件
a.功能说明
跨域资源共享配置和处理。
b.特性说明
预检请求处理、可配置跨域策略。
c.适用场景
前端应用与后端API的跨域通信。
c.限流中间件
a.功能说明
请求频率限制和流量控制。
b.特性说明
多种限流算法、分布式限流支持。
c.适用场景
API保护和服务稳定性保障。
c.业务功能中间件
a.验证中间件
a.功能说明
请求数据验证和参数校验。
b.特性说明
多种验证规则、自定义验证器。
c.适用场景
API参数校验和数据完整性保护。
b.缓存中间件
a.功能说明
响应缓存和缓存策略管理。
b.特性说明
多种缓存后端、缓存失效策略。
c.适用场景
高频查询接口性能优化。
c.重试中间件
a.功能说明
失败请求自动重试和容错处理。
b.特性说明
可配置重试策略、指数退避算法。
c.适用场景
网络请求和服务调用的可靠性提升。
d.服务治理中间件
a.熔断中间件
a.功能说明
服务熔断保护和故障隔离。
b.特性说明
熔断状态管理、自动恢复机制。
c.适用场景
微服务容错和系统稳定性。
b.负载均衡中间件
a.功能说明
请求分发和负载均衡策略。
b.特性说明
多种负载均衡算法、健康检查。
c.适用场景
服务集群和流量分发。
c.服务发现中间件
a.功能说明
动态服务注册和发现。
b.特性说明
多注册中心支持、服务健康检查。
c.适用场景
微服务架构中的服务治理。
02.中间件特性对比
a.特性对比表
中间件类型 性能影响 配置复杂度 必要性 使用频率
日志中间件 低 低 高 极高
监控中间件 中 中 高 高
链路追踪中间件 中 高 中 中
认证中间件 低 中 高 高
CORS中间件 低 低 中 中
限流中间件 低 中 高 中
验证中间件 低 低 高 极高
缓存中间件 低 中 中 中
重试中间件 中 中 中 中
熔断中间件 中 中 高 高
03.生态集成能力
a.第三方中间件支持
a.OpenTelemetry集成
标准化遥测数据收集。
b.Prometheus集成
指标监控和告警系统。
c.Consul集成
服务发现和配置管理。
d.Etcd集成
分布式配置存储。
e.Redis集成
缓存和会话管理。
f.MySQL集成
数据库连接和事务管理。
b.中间件市场
a.GitHub生态
大量开源中间件实现。
b.企业贡献
各大互联网公司的内部中间件开源。
c.社区维护
活跃的社区贡献和更新。
04.最佳实践建议
a.中间件选择原则
a.必要性优先
只选择业务真正需要的中间件。
b.性能考量
评估中间件对服务性能的影响。
c.维护成本
考虑中间件的学习和维护成本。
d.社区支持
选择有活跃社区支持的中间件。
b.中间件组合策略
a.渐进式集成
逐步添加中间件，避免一次性引入过多。
b.分层设计
不同层次使用不同类型的中间件。
c.配置隔离
将中间件配置与业务代码分离。
d.监控集成
确保所有中间件都集成到监控体系。
c.性能优化建议
a.中间件顺序优化
将高频中间件放在前面。
b.缓存策略
合理使用缓存减少重复计算。
c.异步处理
对于耗时操作使用异步中间件。
d.资源池化
复用中间件中的资源对象。
6.2 核心中间件实现
01.中间件机制原理
a.中间件接口定义
a.接口说明
定义了中间件和处理器的标准接口，实现链式调用机制。
b.代码示例
---
// Middleware 中间件接口
type Middleware func(handler Handler) Handler
// Handler 处理器接口
type Handler func(ctx context.Context, req interface{}) (interface{}, error)
---
b.执行流程图
请求 → 中间件1 → 中间件2 → 中间件3 → 业务处理器
↑ ↓ ↑ ↓
后置处理 后置处理 后置处理 响应
02.日志中间件实现
a.基础日志中间件
a.功能说明
统一的请求日志记录和格式化，包含请求ID、方法、路径等信息。
b.核心特性
自动生成请求ID、记录处理时间、结构化日志输出。
c.代码示例
---
// LoggingMiddleware 日志中间件
func LoggingMiddleware(logger log.Logger) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 获取请求信息
var method, path string
if info, ok := transport.FromServerContext(ctx); ok {
method = info.Operation()
path = strings.Join(info.RawMethod(), ".")
}
// 生成请求ID
requestID := metadata.Value(ctx, metadata.RequestIDKey)
if len(requestID) == 0 {
requestID = []string{generateRequestID()}
ctx = metadata.NewContext(ctx, metadata.RequestIDKey, requestID)
}
// 记录请求开始时间
start := time.Now()
// 记录请求日志
_ = log.WithContext(ctx, logger).Infow(
"request started",
"request_id", requestID[0],
"method", method,
"path", path,
"request", req,
)
// 调用下一个处理器
resp, err := handler(ctx, req)
// 计算处理时间
duration := time.Since(start)
// 记录响应日志
logFields := []interface{}{
"request_id", requestID[0],
"method", method,
"path", path,
"duration", duration.String(),
}
if err != nil {
_ = log.WithContext(ctx, logger).Errorw(
"request failed",
append(logFields, "error", err.Error())...,
)
} else {
_ = log.WithContext(ctx, logger).Infow(
"request completed",
append(logFields, "response", resp)...,
)
}
return resp, err
}
}
}
---
b.结构化日志中间件
a.功能说明
提供更详细的结构化日志记录，包含用户信息、客户端IP、用户代理等。
b.增强特性
提取用户信息、客户端详细信息、响应大小计算。
c.代码示例
---
// StructuredLoggingMiddleware 结构化日志中间件
func StructuredLoggingMiddleware(logger log.Logger) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
start := time.Now()
requestID := GetRequestID(ctx)
// 提取用户信息
var userID string
if claims, ok := GetUserClaims(ctx); ok {
userID = claims.UserID
}
// 提取客户端信息
var clientIP, userAgent string
if info, ok := transport.FromServerContext(ctx); ok {
clientIP = getClientIP(info)
userAgent = getUserAgent(info)
}
// 调用下一个处理器
resp, err := handler(ctx, req)
duration := time.Since(start)
// 构建日志结构
logData := map[string]interface{}{
"timestamp": time.Now().Format(time.RFC3339),
"request_id": requestID,
"user_id": userID,
"client_ip": clientIP,
"user_agent": userAgent,
"method": getMethod(ctx),
"path": getPath(ctx),
"duration_ms": duration.Milliseconds(),
"success": err == nil,
}
if err != nil {
logData["error"] = err.Error()
_ = log.WithContext(ctx, logger).Errorw("api_error", logData)
} else {
logData["response_size"] = calculateSize(resp)
_ = log.WithContext(ctx, logger).Infow("api_success", logData)
}
return resp, err
}
}
}
---
03.监控中间件实现
a.Prometheus监控中间件
a.功能说明
收集请求计数、响应时间、错误统计等性能指标，支持Prometheus格式输出。
b.指标类型
RequestCounter、RequestDuration、ErrorCounter等核心指标。
c.代码示例
---
// PrometheusMetricsMiddleware Prometheus 监控中间件
func PrometheusMetricsMiddleware(metrics *Metrics) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
start := time.Now()
// 提取请求信息
method := getMethod(ctx)
path := getPath(ctx)
// 调用下一个处理器
resp, err := handler(ctx, req)
// 计算处理时间
duration := time.Since(start).Seconds()
// 记录指标
metrics.RequestCounter.WithLabelValues(
method, path, getStatusCode(err),
).Inc()
metrics.RequestDuration.WithLabelValues(
method, path,
).Observe(duration)
// 记录错误
if err != nil {
metrics.ErrorCounter.WithLabelValues(
method, path, getErrorType(err),
).Inc()
}
return resp, err
}
}
}
// Metrics 监控指标结构
type Metrics struct {
RequestCounter *prometheus.CounterVec
RequestDuration *prometheus.HistogramVec
ErrorCounter *prometheus.CounterVec
}
// NewMetrics 创建监控指标
func NewMetrics() *Metrics {
return &Metrics{
RequestCounter: prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_requests_total",
Help: "Total number of HTTP requests",
},
[]string{"method", "path", "status"},
),
RequestDuration: prometheus.NewHistogramVec(
prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "HTTP request duration in seconds",
Buckets: prometheus.DefBuckets,
},
[]string{"method", "path"},
),
ErrorCounter: prometheus.NewCounterVec(
prometheus.CounterOpts{
Name: "http_errors_total",
Help: "Total number of HTTP errors",
},
[]string{"method", "path", "error_type"},
),
}
}
---
04.链路追踪中间件实现
a.OpenTelemetry链路追踪中间件
a.功能说明
基于OpenTelemetry标准实现分布式链路追踪，支持Span创建和属性设置。
b.追踪能力
自动创建Span、设置请求属性、记录响应结果和错误信息。
c.代码示例
---
// TracingMiddleware 链路追踪中间件
func TracingMiddleware(tp *sdktrace.TracerProvider) Middleware {
tracer := tp.Tracer("kratos-server")
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 获取请求信息
method := getMethod(ctx)
path := getPath(ctx)
// 创建或获取 Span
spanName := fmt.Sprintf("%s %s", method, path)
ctx, span := tracer.Start(
ctx,
spanName,
trace.WithAttributes(
attribute.String("http.method", method),
attribute.String("http.path", path),
attribute.String("service.name", getServiceName()),
),
)
defer span.End()
// 添加请求信息到 Span
if req != nil {
span.SetAttributes(
attribute.String("request.size", calculateSize(req)),
)
}
// 调用下一个处理器
resp, err := handler(ctx, req)
// 记录响应信息
if err != nil {
span.SetAttributes(
attribute.String("error", err.Error()),
attribute.Bool("success", false),
)
span.SetStatus(codes.Error, err.Error())
} else {
span.SetAttributes(
attribute.Bool("success", true),
attribute.String("response.size", calculateSize(resp)),
)
span.SetStatus(codes.Ok, "success")
}
return resp, err
}
}
}
---
b.Jaeger链路追踪中间件
a.功能说明
基于Jaeger实现分布式链路追踪，支持OpenTracing标准。
b.集成特性
Span传播、上下文注入、错误标记和状态设置。
c.代码示例
---
// JaegerTracingMiddleware Jaeger 链路追踪中间件
func JaegerTracingMiddleware(serviceName string, tracer opentracing.Tracer) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 尝试从上下文中提取现有的 Span
var span opentracing.Span
if parentSpan := opentracing.SpanFromContext(ctx); parentSpan != nil {
span = tracer.StartSpan(
getOperationName(ctx),
opentracing.ChildOf(parentSpan.Context()),
)
} else {
span = tracer.StartSpan(getOperationName(ctx))
}
defer span.Finish()
// 设置 Span 标签
span.SetTag("service.name", serviceName)
span.SetTag("http.method", getMethod(ctx))
span.SetTag("http.path", getPath(ctx))
// 将 Span 注入到上下文
ctx = opentracing.ContextWithSpan(ctx, span)
// 调用下一个处理器
resp, err := handler(ctx, req)
// 记录错误信息
if err != nil {
span.SetTag("error", true)
span.SetTag("error.message", err.Error())
ext.Error.Set(span, true)
} else {
span.SetTag("success", true)
}
return resp, err
}
}
}
---
05.认证中间件实现
a.JWT认证中间件
a.功能说明
基于JWT令牌实现用户身份认证和授权验证。
b.验证流程
提取Token、验证签名、检查过期时间、注入用户信息。
c.代码示例
---
// JWTAuthMiddleware JWT 认证中间件
func JWTAuthMiddleware(secretKey string, skipPaths []string) Middleware {
skipPathMap := make(map[string]bool)
for _, path := range skipPaths {
skipPathMap[path] = true
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 检查是否跳过认证
path := getPath(ctx)
if skipPathMap[path] {
return handler(ctx, req)
}
// 从请求头中提取 Token
token, err := extractTokenFromHeader(ctx)
if err != nil {
return nil, errors.Unauthorized("AUTH_TOKEN_MISSING", "authentication token is required")
}
// 验证 Token
claims, err := validateJWTToken(token, secretKey)
if err != nil {
return nil, errors.Unauthorized("AUTH_TOKEN_INVALID", fmt.Sprintf("invalid token: %v", err))
}
// 检查 Token 是否过期
if time.Now().Unix() > claims.ExpiresAt.Unix() {
return nil, errors.Unauthorized("AUTH_TOKEN_EXPIRED", "token has expired")
}
// 将用户信息注入到上下文
ctx = NewUserContext(ctx, claims)
return handler(ctx, req)
}
}
}
// JWTClaims JWT 声明结构
type JWTClaims struct {
UserID string `json:"user_id"`
Username string `json:"username"`
Roles []string `json:"roles"`
ExpiresAt int64 `json:"exp"`
IssuedAt int64 `json:"iat"`
}
---
b.OAuth2认证中间件
a.功能说明
支持OAuth2标准认证流程，集成第三方认证服务。
b.验证机制
访问令牌验证、权限范围检查、令牌信息提取。
c.代码示例
---
// OAuth2AuthMiddleware OAuth2 认证中间件
func OAuth2AuthMiddleware(config *OAuth2Config) Middleware {
oauth2Config := &oauth2.Config{
ClientID: config.ClientID,
ClientSecret: config.ClientSecret,
Scopes: config.Scopes,
Endpoint: oauth2.Endpoint{
AuthURL: config.AuthURL,
TokenURL: config.TokenURL,
},
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 提取访问令牌
accessToken, err := extractAccessToken(ctx)
if err != nil {
return nil, errors.Unauthorized("OAUTH2_TOKEN_MISSING", "access token is required")
}
// 验证访问令牌
tokenInfo, err := validateOAuth2Token(accessToken, oauth2Config)
if err != nil {
return nil, errors.Unauthorized("OAUTH2_TOKEN_INVALID", fmt.Sprintf("invalid access token: %v", err))
}
// 检查权限范围
requiredScopes := getRequiredScopes(ctx)
if !hasRequiredScopes(tokenInfo.Scopes, requiredScopes) {
return nil, errors.Forbidden("OAUTH2_INSUFFICIENT_SCOPE", "insufficient scope")
}
// 将用户信息注入到上下文
ctx = NewOAuth2Context(ctx, tokenInfo)
return handler(ctx, req)
}
}
}
---
06.验证中间件实现
a.参数验证中间件
a.功能说明
对请求数据进行自动验证和参数校验，支持多种验证规则。
b.验证能力
结构体验证、字段验证、错误消息格式化。
c.代码示例
---
// ValidationMiddleware 参数验证中间件
func ValidationMiddleware() Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 如果请求为空，直接返回错误
if req == nil {
return nil, errors.BadRequest("VALIDATION_ERROR", "request body is required")
}
// 执行验证
if err := validator.New().Struct(req); err != nil {
// 处理验证错误
validationErrors := make(map[string]string)
for _, fieldErr := range err.(validator.ValidationErrors) {
fieldName := fieldErr.Field()
errorMsg := getValidationErrorMessage(fieldErr)
validationErrors[fieldName] = errorMsg
}
return nil, errors.BadRequest("VALIDATION_ERROR",
fmt.Sprintf("validation failed: %v", validationErrors))
}
return handler(ctx, req)
}
}
}
// getValidationErrorMessage 获取验证错误消息
func getValidationErrorMessage(fieldErr validator.FieldError) string {
switch fieldErr.Tag() {
case "required":
return "field is required"
case "email":
return "invalid email format"
case "min":
return fmt.Sprintf("must be at least %s characters", fieldErr.Param())
case "max":
return fmt.Sprintf("must be at most %s characters", fieldErr.Param())
default:
return fmt.Sprintf("invalid %s", fieldErr.Tag())
}
}
---
07.限流中间件实现
a.基于Token Bucket的限流中间件
a.功能说明
使用令牌桶算法实现请求频率限制，支持分布式限流。
b.限流策略
固定速率限流、突发流量处理、令牌桶大小配置。
c.代码示例
---
// RateLimitingMiddleware 限流中间件
func RateLimitingMiddleware(limiter *rate.Limiter) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 检查是否超过限流阈值
if !limiter.Allow() {
return nil, errors.TooManyRequests("RATE_LIMIT_EXCEEDED",
"request rate limit exceeded")
}
return handler(ctx, req)
}
}
}
// SlidingWindowRateLimitingMiddleware 滑动窗口限流中间件
func SlidingWindowRateLimitingMiddleware(windowSize time.Duration, maxRequests int) Middleware {
requests := make(map[string][]time.Time)
var mutex sync.RWMutex
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 获取客户端标识（IP或用户ID）
clientID := getClientIdentifier(ctx)
mutex.Lock()
defer mutex.Unlock()
now := time.Now()
windowStart := now.Add(-windowSize)
// 清理过期记录
if timestamps, exists := requests[clientID]; exists {
var validTimestamps []time.Time
for _, timestamp := range timestamps {
if timestamp.After(windowStart) {
validTimestamps = append(validTimestamps, timestamp)
}
}
requests[clientID] = validTimestamps
}
// 检查请求数量
if len(requests[clientID]) >= maxRequests {
return nil, errors.TooManyRequests("RATE_LIMIT_EXCEEDED",
"sliding window rate limit exceeded")
}
// 记录当前请求
requests[clientID] = append(requests[clientID], now)
return handler(ctx, req)
}
}
}
---
08.中间件组合使用
a.中间件链构建
a.功能说明
构建完整的中间件链，按正确顺序应用多个中间件。
b.构建原则
反向应用中间件、按照优先级排序、确保执行顺序正确。
c.代码示例
---
// BuildMiddlewareChain 构建中间件链
func BuildMiddlewareChain(handler Handler, middlewares ...Middleware) Handler {
// 反向应用中间件，确保执行顺序正确
for i := len(middlewares) - 1; i >= 0; i-- {
handler = middlewares[i](handler)
}
return handler
}
// 创建服务器中间件链
func CreateServerMiddlewareChain(config *Config, logger log.Logger) []Middleware {
var middlewares []Middleware
// 基础中间件
middlewares = append(middlewares,
RecoveryMiddleware(logger),
RequestIDMiddleware(),
LoggingMiddleware(logger),
MetricsMiddleware(),
)
// 安全中间件
if config.Security.Enabled {
middlewares = append(middlewares,
CORSMiddleware(config.CORS),
RateLimitingMiddleware(config.RateLimit),
JWTAuthMiddleware(config.JWT),
)
}
// 追踪中间件
if config.Tracing.Enabled {
middlewares = append(middlewares,
TracingMiddleware(config.Tracing),
)
}
// 业务中间件
middlewares = append(middlewares,
ValidationMiddleware(),
TimeoutMiddleware(config.Server.Timeout),
)
return middlewares
}
---
6.3 自定义中间件开发
01.中间件开发基础
在Kratos框架中，自定义中间件需要遵循标准的开发规范和接口定义。
a.中间件接口规范
a.接口定义说明
自定义中间件需要实现标准的中间件接口，支持配置选项模式。
b.接口模板
---
// Middleware 中间件接口定义
type Middleware func(handler Handler) Handler
// Handler 处理器接口
type Handler func(ctx context.Context, req interface{}) (interface{}, error)
// 自定义中间件示例模板
func CustomMiddleware(options ...Option) Middleware {
// 初始化中间件配置
config := DefaultConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 前置处理逻辑
ctx, err := beforeProcess(ctx, req, config)
if err != nil {
return nil, err
}
// 调用下一个处理器
resp, err := handler(ctx, req)
// 后置处理逻辑
resp, err = afterProcess(ctx, req, resp, err, config)
return resp, err
}
}
}
---
b.配置选项模式
a.配置结构
定义中间件的配置结构，支持YAML配置和选项模式。
b.选项函数
实现函数式选项模式，提供灵活的配置方式。
c.配置示例
---
// Config 中间件配置结构
type Config struct {
Enabled bool `yaml:"enabled"`
Timeout time.Duration `yaml:"timeout"`
MaxRetries int `yaml:"max_retries"`
Debug bool `yaml:"debug"`
}
// Option 配置选项函数
type Option func(*Config)
// DefaultConfig 默认配置
func DefaultConfig() *Config {
return &Config{
Enabled: true,
Timeout: 30 * time.Second,
MaxRetries: 3,
Debug: false,
}
}
// WithEnabled 设置启用状态
func WithEnabled(enabled bool) Option {
return func(c *Config) {
c.Enabled = enabled
}
}
// WithTimeout 设置超时时间
func WithTimeout(timeout time.Duration) Option {
return func(c *Config) {
c.Timeout = timeout
}
}
// WithDebug 设置调试模式
func WithDebug(debug bool) Option {
return func(c *Config) {
c.Debug = debug
}
}
---
02.业务中间件开发示例
通过具体的业务中间件示例，展示如何开发符合业务需求的自定义中间件。
a.业务审计中间件
a.功能概述
记录关键业务操作的审计日志，支持异步记录和数据脱敏。
b.核心特性
审计信息提取、敏感数据脱敏、异步批量记录。
c.实现示例
---
// AuditMiddleware 业务审计中间件
func AuditMiddleware(auditor Auditor, options ...Option) Middleware {
config := DefaultAuditConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
if !config.Enabled {
return handler(ctx, req)
}
start := time.Now()
// 提取审计信息
auditInfo := &AuditInfo{
RequestID: GetRequestID(ctx),
UserID: GetUserID(ctx),
Method: GetMethod(ctx),
Path: GetPath(ctx),
ClientIP: GetClientIP(ctx),
UserAgent: GetUserAgent(ctx),
RequestTime: start,
RequestData: sanitizeRequestData(req, config.SanitizeFields),
}
// 调用下一个处理器
resp, err := handler(ctx, req)
// 更新审计信息
auditInfo.Duration = time.Since(start)
auditInfo.Success = err == nil
auditInfo.ResponseData = sanitizeResponseData(resp, config.SanitizeFields)
if err != nil {
auditInfo.ErrorMessage = err.Error()
auditInfo.ErrorCode = getErrorCode(err)
}
// 异步记录审计日志
go func() {
if err := auditor.Record(ctx, auditInfo); err != nil {
// 记录审计失败日志
log.Errorf("failed to record audit log: %v", err)
}
}()
return resp, err
}
}
}
// AuditInfo 审计信息结构
type AuditInfo struct {
RequestID string `json:"request_id"`
UserID string `json:"user_id"`
Method string `json:"method"`
Path string `json:"path"`
ClientIP string `json:"client_ip"`
UserAgent string `json:"user_agent"`
RequestTime time.Time `json:"request_time"`
Duration time.Duration `json:"duration"`
Success bool `json:"success"`
RequestData map[string]interface{} `json:"request_data"`
ResponseData map[string]interface{} `json:"response_data"`
ErrorMessage string `json:"error_message,omitempty"`
ErrorCode string `json:"error_code,omitempty"`
}
// Auditor 审计记录器接口
type Auditor interface {
Record(ctx context.Context, info *AuditInfo) error
}
---
b.数据脱敏中间件
a.功能概述
对请求和响应中的敏感数据进行自动脱敏处理，保护用户隐私。
b.脱敏规则
支持手机号、邮箱、身份证、银行卡等多种敏感数据类型的脱敏。
c.实现示例
---
// DataMaskingMiddleware 数据脱敏中间件
func DataMaskingMiddleware(masker DataMasker, options ...Option) Middleware {
config := DefaultMaskingConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 脱敏请求数据
maskedReq := masker.MaskRequest(req, config.MaskingRules)
// 调用下一个处理器
resp, err := handler(ctx, maskedReq)
// 脱敏响应数据
if resp != nil {
maskedResp := masker.MaskResponse(resp, config.MaskingRules)
return maskedResp, err
}
return resp, err
}
}
}
// DataMasker 数据脱敏器接口
type DataMasker interface {
MaskRequest(req interface{}, rules []MaskingRule) interface{}
MaskResponse(resp interface{}, rules []MaskingRule) interface{}
}
// MaskingRule 脱敏规则
type MaskingRule struct {
Field string `yaml:"field"`
Type MaskingType `yaml:"type"`
Pattern string `yaml:"pattern,omitempty"`
Replace string `yaml:"replace,omitempty"`
Options map[string]string `yaml:"options,omitempty"`
}
// MaskingType 脱敏类型
type MaskingType string
const (
MaskingTypePhone MaskingType = "phone"
MaskingTypeEmail MaskingType = "email"
MaskingTypeIDCard MaskingType = "idcard"
MaskingTypeBankCard MaskingType = "bankcard"
MaskingTypeCustom MaskingType = "custom"
MaskingTypeFull MaskingType = "full"
)
// DefaultDataMasker 默认数据脱敏器实现
type DefaultDataMasker struct{}
// MaskRequest 脱敏请求数据
func (m *DefaultDataMasker) MaskRequest(req interface{}, rules []MaskingRule) interface{} {
return m.maskData(req, rules)
}
// MaskResponse 脱敏响应数据
func (m *DefaultDataMasker) MaskResponse(resp interface{}, rules []MaskingRule) interface{} {
return m.maskData(resp, rules)
}
// maskData 脱敏数据
func (m *DefaultDataMasker) maskData(data interface{}, rules []MaskingRule) interface{} {
// 将数据转换为 map
dataMap, err := structToMap(data)
if err != nil {
return data
}
// 应用脱敏规则
for _, rule := range rules {
if value, exists := dataMap[rule.Field]; exists {
dataMap[rule.Field] = m.applyMasking(value, rule)
}
}
return dataMap
}
// applyMasking 应用脱敏规则
func (m *DefaultDataMasker) applyMasking(value interface{}, rule MaskingRule) interface{} {
strValue, ok := value.(string)
if !ok {
return value
}
switch rule.Type {
case MaskingTypePhone:
return maskPhone(strValue)
case MaskingTypeEmail:
return maskEmail(strValue)
case MaskingTypeIDCard:
return maskIDCard(strValue)
case MaskingTypeBankCard:
return maskBankCard(strValue)
case MaskingTypeFull:
return strings.Repeat("*", len(strValue))
case MaskingTypeCustom:
return maskCustom(strValue, rule.Pattern, rule.Replace)
default:
return value
}
}
// maskPhone 脱敏手机号
func maskPhone(phone string) string {
if len(phone) != 11 {
return phone
}
return phone[:3] + "****" + phone[7:]
}
// maskEmail 脱敏邮箱
func maskEmail(email string) string {
parts := strings.Split(email, "@")
if len(parts) != 2 {
return email
}
username := parts[0]
domain := parts[1]
if len(username) <= 3 {
return strings.Repeat("*", len(username)) + "@" + domain
}
return username[:2] + strings.Repeat("*", len(username)-2) + "@" + domain
}
---
c.业务规则引擎中间件
a.功能概述
集成业务规则引擎，在请求处理过程中执行业务规则验证和控制。
b.规则执行
支持前置规则执行、后置规则执行、规则上下文管理。
c.实现示例
---
// BusinessRuleMiddleware 业务规则引擎中间件
func BusinessRuleMiddleware(engine RuleEngine, options ...Option) Middleware {
config := DefaultRuleConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
if !config.Enabled {
return handler(ctx, req)
}
// 构建规则执行上下文
ruleCtx := &RuleContext{
RequestID: GetRequestID(ctx),
UserID: GetUserID(ctx),
Method: GetMethod(ctx),
Path: GetPath(ctx),
Request: req,
Time: time.Now(),
}
// 执行前置规则
if err := engine.ExecuteBeforeRules(ruleCtx, config.BeforeRules); err != nil {
return nil, errors.Forbidden("RULE_VIOLATION", err.Error())
}
// 调用下一个处理器
resp, err := handler(ctx, req)
// 执行后置规则
if err == nil {
ruleCtx.Response = resp
if err := engine.ExecuteAfterRules(ruleCtx, config.AfterRules); err != nil {
// 记录规则违规，但不影响响应
log.Warnf("after rule violation: %v", err)
}
}
return resp, err
}
}
}
// RuleEngine 规则引擎接口
type RuleEngine interface {
ExecuteBeforeRules(ctx *RuleContext, rules []string) error
ExecuteAfterRules(ctx *RuleContext, rules []string) error
}
// RuleContext 规则执行上下文
type RuleContext struct {
RequestID string `json:"request_id"`
UserID string `json:"user_id"`
Method string `json:"method"`
Path string `json:"path"`
Request interface{} `json:"request"`
Response interface{} `json:"response"`
Time time.Time `json:"time"`
Variables map[string]interface{} `json:"variables"`
}
---
03.性能优化中间件
开发用于性能优化的中间件，提升系统的响应速度和资源利用效率。
a.缓存中间件
a.功能概述
提供智能缓存功能，减少重复计算和数据库查询。
b.缓存策略
支持多种缓存后端、键值生成、TTL管理、缓存失效策略。
c.实现示例
---
// CacheMiddleware 缓存中间件
func CacheMiddleware(cache Cache, keyGenerator KeyGenerator, options ...Option) Middleware {
config := DefaultCacheConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
if !config.Enabled || shouldSkipCache(ctx, config.SkipMethods) {
return handler(ctx, req)
}
// 生成缓存键
cacheKey := keyGenerator.Generate(ctx, req)
// 尝试从缓存获取
if cachedResp, err := cache.Get(ctx, cacheKey); err == nil {
// 命中缓存
recordCacheHit(ctx, cacheKey)
return cachedResp, nil
}
// 缓存未命中，调用处理器
resp, err := handler(ctx, req)
if err != nil {
return nil, err
}
// 缓存响应
if shouldCacheResponse(resp, config.CacheableStatuses) {
ttl := calculateTTL(resp, config.DefaultTTL)
go func() {
if err := cache.Set(context.Background(), cacheKey, resp, ttl); err != nil {
log.Warnf("failed to cache response: %v", err)
}
}()
}
recordCacheMiss(ctx, cacheKey)
return resp, err
}
}
}
// Cache 缓存接口
type Cache interface {
Get(ctx context.Context, key string) (interface{}, error)
Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
Delete(ctx context.Context, key string) error
}
// KeyGenerator 缓存键生成器接口
type KeyGenerator interface {
Generate(ctx context.Context, req interface{}) string
}
// DefaultKeyGenerator 默认键生成器
type DefaultKeyGenerator struct{}
// Generate 生成缓存键
func (g *DefaultKeyGenerator) Generate(ctx context.Context, req interface{}) string {
method := GetMethod(ctx)
path := GetPath(ctx)
userID := GetUserID(ctx)
// 序列化请求对象
reqHash, _ := hashRequest(req)
return fmt.Sprintf("%s:%s:%s:%s", method, path, userID, reqHash)
}
---
b.压缩中间件
a.功能概述
对响应数据进行压缩，减少网络传输量，提高传输效率。
b.压缩策略
支持多种压缩算法、自适应压缩、压缩阈值控制。
c.实现示例
---
// CompressionMiddleware 压缩中间件
func CompressionMiddleware(options ...Option) Middleware {
config := DefaultCompressionConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 调用下一个处理器
resp, err := handler(ctx, req)
if err != nil {
return nil, err
}
// 检查是否需要压缩
if !shouldCompress(ctx, resp, config) {
return resp, nil
}
// 执行压缩
compressedResp, err := compressResponse(resp, config.CompressionLevel)
if err != nil {
log.Warnf("compression failed: %v", err)
return resp, nil // 压缩失败时返回原始响应
}
// 设置压缩标识
setCompressionHeader(ctx, config.CompressionType)
return compressedResp, nil
}
}
}
// shouldCompress 判断是否需要压缩
func shouldCompress(ctx context.Context, resp interface{}, config *CompressionConfig) bool {
// 检查客户端是否支持压缩
acceptEncoding := getAcceptEncoding(ctx)
if !supportsCompression(acceptEncoding, config.CompressionType) {
return false
}
// 检查响应大小
size := calculateSize(resp)
return size >= config.MinSize
}
---
04.中间件测试
通过完整的测试框架和示例，确保中间件的质量和稳定性。
a.单元测试框架
a.测试结构
定义标准的测试结构和模拟对象，支持中间件的单元测试。
b.模拟机制
提供Mock处理器和上下文，简化测试环境搭建。
c.测试示例
---
// middleware_test.go
package middleware
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/mock"
)
// MockHandler 模拟处理器
type MockHandler struct {
mock.Mock
}
func (m *MockHandler) Handle(ctx context.Context, req interface{}) (interface{}, error) {
args := m.Called(ctx, req)
return args.Get(0), args.Error(1)
}
// TestCustomMiddleware 测试自定义中间件
func TestCustomMiddleware(t *testing.T) {
tests := []struct {
name string
config *Config
request interface{}
expectedResp interface{}
expectedErr error
setupMocks func(*MockHandler)
verifyBehavior func(*testing.T, context.Context)
}{
{
name: "success case",
config: &Config{Enabled: true},
request: map[string]interface{}{
"key": "value",
},
expectedResp: map[string]interface{}{
"result": "success",
},
expectedErr: nil,
setupMocks: func(handler *MockHandler) {
handler.On("Handle", mock.Anything, mock.Anything).
Return(map[string]interface{}{"result": "success"}, nil)
},
verifyBehavior: func(t *testing.T, ctx context.Context) {
// 验证中间件添加的上下文值
assert.NotEmpty(t, ctx.Value("middleware_executed"))
},
},
{
name: "middleware disabled",
config: &Config{Enabled: false},
request: map[string]interface{}{
"key": "value",
},
expectedResp: map[string]interface{}{
"result": "success",
},
expectedErr: nil,
setupMocks: func(handler *MockHandler) {
handler.On("Handle", mock.Anything, mock.Anything).
Return(map[string]interface{}{"result": "success"}, nil)
},
verifyBehavior: func(t *testing.T, ctx context.Context) {
// 验证中间件未执行
assert.Empty(t, ctx.Value("middleware_executed"))
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
// 创建模拟处理器
mockHandler := &MockHandler{}
tt.setupMocks(mockHandler)
// 创建中间件
middleware := CustomMiddleware(tt.config)
// 包装处理器
wrappedHandler := middleware(mockHandler.Handle)
// 执行测试
ctx := context.Background()
resp, err := wrappedHandler(ctx, tt.request)
// 验证结果
assert.Equal(t, tt.expectedResp, resp)
assert.Equal(t, tt.expectedErr, err)
// 验证行为
tt.verifyBehavior(t, ctx)
// 验证模拟调用
mockHandler.AssertExpectations(t)
})
}
}
---
b.基准测试
a.性能测试
通过基准测试评估中间件的性能影响，确保性能满足要求。
b.测试指标
测量中间件的执行时间、内存分配、吞吐量等关键指标。
c.基准示例
---
// BenchmarkCustomMiddleware 中间件基准测试
func BenchmarkCustomMiddleware(b *testing.B) {
config := &Config{Enabled: true}
middleware := CustomMiddleware(config)
handler := func(ctx context.Context, req interface{}) (interface{}, error) {
return map[string]interface{}{"result": "success"}, nil
}
wrappedHandler := middleware(handler)
ctx := context.Background()
req := map[string]interface{}{"key": "value"}
b.ResetTimer()
b.RunParallel(func(pb *testing.PB) {
for pb.Next() {
_, err := wrappedHandler(ctx, req)
if err != nil {
b.Fatal(err)
}
}
})
}
---
05.中间件部署
提供完整的部署配置和管理方案，支持不同环境的中间件部署。
a.中间件配置
a.配置文件格式
支持YAML格式的配置文件，包含各类中间件的配置参数。
b.环境变量支持
支持通过环境变量覆盖配置，便于容器化部署。
c.配置示例
---
# middleware.yaml
middleware:
custom:
enabled: true
timeout: 30s
max_retries: 3
debug: false
audit:
enabled: true
async: true
batch_size: 100
flush_interval: 5s
sanitize_fields:
- password
- token
- secret
compression:
enabled: true
compression_type: gzip
compression_level: 6
min_size: 1024
cache:
enabled: true
default_ttl: 300s
skip_methods:
- POST
- PUT
- DELETE
---
b.中间件注册
a.注册机制
提供统一的中间件注册接口，支持动态添加和移除中间件。
b.依赖管理
支持中间件依赖关系管理，确保正确的加载顺序。
c.注册示例
---
// 注册自定义中间件
func RegisterCustomMiddlewares(app *kratos.App) {
// 创建中间件实例
customMiddleware := CustomMiddleware(
WithEnabled(true),
WithTimeout(30*time.Second),
)
auditMiddleware := AuditMiddleware(
&DefaultAuditor{},
WithAsync(true),
WithBatchSize(100),
)
compressionMiddleware := CompressionMiddleware(
WithCompressionType("gzip"),
WithMinSize(1024),
)
// 注册中间件
app.Use(customMiddleware)
app.Use(auditMiddleware)
app.Use(compressionMiddleware)
}
---
6.4 服务间调用 Middleware
01.服务调用中间件概述
在微服务架构中，服务间的通信是一个核心问题。Kratos框架提供了专门用于服务间调用的中间件机制，这些中间件可以在客户端和服务端两个层面工作，为分布式调用提供额外的功能支持。
a.调用中间件分类
a.客户端中间件
在发起服务调用前执行的中间件，负责请求预处理和调用控制。
b.服务端中间件
在接收到服务调用时执行的中间件，负责请求处理和响应生成。
c.拦截器中间件
可以在调用前后都执行逻辑的中间件，提供完整的调用生命周期管理。
02.客户端调用中间件
提供丰富的客户端调用中间件，支持重试、熔断、限流等功能。
a.重试中间件
a.功能概述
实现自动重试机制，提高服务调用的可靠性和容错能力。
b.重试策略
支持多种重试算法、可配置重试次数、智能退避策略。
c.实现示例
---
// RetryMiddleware 客户端重试中间件
func RetryMiddleware(options ...RetryOption) Middleware {
config := DefaultRetryConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
var lastErr error
for attempt := 0; attempt <= config.MaxAttempts; attempt++ {
if attempt > 0 {
// 等待重试间隔
backoff := calculateBackoff(attempt, config)
select {
case <-time.After(backoff):
case <-ctx.Done():
return nil, ctx.Err()
}
}
// 执行调用
resp, err := handler(ctx, req)
if err == nil {
return resp, nil
}
lastErr = err
// 检查是否应该重试
if !shouldRetry(err, config) || attempt == config.MaxAttempts {
break
}
// 记录重试日志
logRetry(ctx, attempt, err)
}
return nil, enhanceErrorWithRetryInfo(lastErr, config.MaxAttempts)
}
}
}
// RetryConfig 重试配置
type RetryConfig struct {
MaxAttempts int
InitialBackoff time.Duration
MaxBackoff time.Duration
Multiplier float64
RetryableFunc func(error) bool
}
// calculateBackoff 计算退避时间
func calculateBackoff(attempt int, config *RetryConfig) time.Duration {
backoff := time.Duration(float64(config.InitialBackoff) *
math.Pow(config.Multiplier, float64(attempt-1)))
if backoff > config.MaxBackoff {
backoff = config.MaxBackoff
}
// 添加随机抖动
jitter := time.Duration(rand.Float64() * float64(backoff) * 0.1)
return backoff + jitter
}
// shouldRetry 判断是否应该重试
func shouldRetry(err error, config *RetryConfig) bool {
if config.RetryableFunc != nil {
return config.RetryableFunc(err)
}
// 默认重试逻辑
switch {
case isConnectionError(err):
return true
case isTimeoutError(err):
return true
case isTemporaryError(err):
return true
default:
return false
}
}
---
b.熔断中间件
a.功能概述
实现服务熔断保护，防止级联故障，提高系统稳定性。
b.熔断机制
支持熔断状态管理、自动恢复机制、失败率阈值控制。
c.实现示例
---
// CircuitBreakerMiddleware 熔断中间件
func CircuitBreakerMiddleware(cb CircuitBreaker, options ...CBOption) Middleware {
config := DefaultCBConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
serviceName := getServiceName(ctx)
// 检查熔断器状态
if !cb.AllowRequest(serviceName) {
return nil, errors.ServiceUnavailable("CIRCUIT_BREAKER_OPEN",
fmt.Sprintf("circuit breaker is open for service: %s", serviceName))
}
// 记录调用开始
cb.RecordCallStart(serviceName)
// 执行调用
resp, err := handler(ctx, req)
// 记录调用结果
if err != nil {
cb.RecordCallFailure(serviceName)
// 检查是否需要触发熔断
if cb.ShouldTrip(serviceName) {
cb.Trip(serviceName)
}
} else {
cb.RecordCallSuccess(serviceName)
}
return resp, err
}
}
}
// CircuitBreaker 熔断器接口
type CircuitBreaker interface {
AllowRequest(serviceName string) bool
RecordCallStart(serviceName string)
RecordCallSuccess(serviceName string)
RecordCallFailure(serviceName string)
ShouldTrip(serviceName string) bool
Trip(serviceName string)
Reset(serviceName string)
State(serviceName string) CircuitState
}
// CircuitState 熔断器状态
type CircuitState int
const (
CircuitClosed CircuitState = iota
CircuitHalfOpen
CircuitOpen
)
// DefaultCircuitBreaker 默认熔断器实现
type DefaultCircuitBreaker struct {
mu sync.RWMutex
services map[string]*ServiceCircuit
config *CBConfig
}
// ServiceCircuit 服务熔断器
type ServiceCircuit struct {
state CircuitState
generation int64
requests int64
failures int64
lastFailTime time.Time
lastSuccessTime time.Time
}
// CBConfig 熔断器配置
type CBConfig struct {
MaxRequests uint32
Interval time.Duration
Timeout time.Duration
ReadyToTrip func(counts Counts) bool
OnStateChange func(name string, from, to CircuitState)
IsSuccessful func(err error) bool
}
// Counts 计数器
type Counts struct {
Requests uint32
TotalSuccesses uint32
TotalFailures uint32
ConsecutiveSuccesses uint32
ConsecutiveFailures uint32
}
---
c.限流中间件
a.功能概述
实现请求频率控制，保护服务免受过载，提供服务质量保证。
b.限流算法
支持令牌桶、滑动窗口、固定窗口等多种限流算法。
c.实现示例
---
// RateLimitingMiddleware 客户端限流中间件
func RateLimitingMiddleware(limiter RateLimiter, options ...RateLimitOption) Middleware {
config := DefaultRateLimitConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 获取限流键
key := getRateLimitKey(ctx, config.KeyGenerator)
// 检查是否允许请求
allowed, resetTime, err := limiter.Allow(key)
if err != nil {
// 限流器错误时允许通过，记录日志
log.Warnf("rate limiter error: %v", err)
return handler(ctx, req)
}
if !allowed {
return nil, errors.TooManyRequests("RATE_LIMIT_EXCEEDED",
fmt.Sprintf("rate limit exceeded, retry after %v",
time.Until(resetTime)))
}
// 执行调用
return handler(ctx, req)
}
}
}
// RateLimiter 限流器接口
type RateLimiter interface {
Allow(key string) (allowed bool, resetTime time.Time, err error)
SetLimit(key string, limit rate.Limit)
SetBurst(key string, burst int)
}
// RedisRateLimiter Redis 限流器实现
type RedisRateLimiter struct {
client redis.Cmdable
prefix string
}
// Allow 检查是否允许请求
func (r *RedisRateLimiter) Allow(key string) (bool, time.Time, error) {
fullKey := fmt.Sprintf("%s:%s", r.prefix, key)
now := time.Now().Unix()
window := 60 // 1分钟窗口
// 使用滑动窗口算法
script := `
local key = KEYS[1]
local now = tonumber(ARGV[1])
local window = tonumber(ARGV[2])
local limit = tonumber(ARGV[3])
-- 清理过期记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)
-- 获取当前窗口内请求数
local current = redis.call('ZCARD', key)
if current < limit then
-- 记录当前请求
redis.call('ZADD', key, now, now)
redis.call('EXPIRE', key, window)
return {1, now + window}
else
-- 返回最早的请求时间作为重置时间
local oldest = redis.call('ZRANGE', key, 0, 0, 'WITHSCORES')
if #oldest > 0 then
return {0, tonumber(oldest[2]) + window}
else
return {0, now + window}
end
end
`
result, err := r.client.Eval(context.Background(), script,
[]string{fullKey}, now, window, 10).Result()
if err != nil {
return false, time.Time{}, err
}
if slice, ok := result.([]interface{}); ok && len(slice) == 2 {
allowed := slice[0].(int64) == 1
resetTime := time.Unix(slice[1].(int64), 0)
return allowed, resetTime, nil
}
return false, time.Time{}, errors.New("invalid rate limiter response")
}
---
03.服务端调用中间件
提供服务端调用中间件，支持负载均衡、超时控制等功能。
a.负载均衡中间件
a.功能概述
实现智能负载均衡，支持多种算法和健康检查机制。
b.负载均衡算法
支持轮询、加权随机、最少连接、IP哈希等多种算法。
c.实现示例
---
// LoadBalancerMiddleware 负载均衡中间件
func LoadBalancerMiddleware(lb LoadBalancer, options ...LBOption) Middleware {
config := DefaultLBConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 获取服务实例列表
serviceName := getServiceName(ctx)
instances, err := getInstances(serviceName)
if err != nil {
return nil, errors.InternalServer("LOAD_BALANCER_ERROR",
fmt.Sprintf("failed to get service instances: %v", err))
}
// 选择目标实例
instance, err := lb.Select(instances, config.Strategy)
if err != nil {
return nil, errors.InternalServer("LOAD_BALANCER_ERROR",
fmt.Sprintf("failed to select instance: %v", err))
}
// 将选中的实例信息注入到上下文
ctx = SetTargetInstance(ctx, instance)
// 执行调用
return handler(ctx, req)
}
}
}
// LoadBalancer 负载均衡器接口
type LoadBalancer interface {
Select(instances []ServiceInstance, strategy LBStrategy) (*ServiceInstance, error)
}
// ServiceInstance 服务实例
type ServiceInstance struct {
ID string `json:"id"`
Name string `json:"name"`
Address string `json:"address"`
Port int `json:"port"`
Weight int `json:"weight"`
Metadata map[string]string `json:"metadata"`
Status InstanceStatus `json:"status"`
}
// LBStrategy 负载均衡策略
type LBStrategy string
const (
LBStrategyRoundRobin LBStrategy = "round_robin"
LBStrategyWeightedRandom LBStrategy = "weighted_random"
LBStrategyLeastConn LBStrategy = "least_conn"
LBStrategyIPHash LBStrategy = "ip_hash"
)
// DefaultLoadBalancer 默认负载均衡器实现
type DefaultLoadBalancer struct {
mu sync.Mutex
counters map[string]int
}
// Select 选择服务实例
func (lb *DefaultLoadBalancer) Select(instances []ServiceInstance, strategy LBStrategy) (*ServiceInstance, error) {
if len(instances) == 0 {
return nil, errors.New("no available instances")
}
// 过滤健康实例
healthyInstances := filterHealthyInstances(instances)
if len(healthyInstances) == 0 {
return nil, errors.New("no healthy instances available")
}
switch strategy {
case LBStrategyRoundRobin:
return lb.selectRoundRobin(healthyInstances)
case LBStrategyWeightedRandom:
return lb.selectWeightedRandom(healthyInstances)
case LBStrategyLeastConn:
return lb.selectLeastConn(healthyInstances)
case LBStrategyIPHash:
return lb.selectIPHash(healthyInstances)
default:
return lb.selectRoundRobin(healthyInstances)
}
}
// selectRoundRobin 轮询选择
func (lb *DefaultLoadBalancer) selectRoundRobin(instances []ServiceInstance) (*ServiceInstance, error) {
lb.mu.Lock()
defer lb.mu.Unlock()
key := instances[0].Name
if lb.counters == nil {
lb.counters = make(map[string]int)
}
index := lb.counters[key] % len(instances)
lb.counters[key] = index + 1
return &instances[index], nil
}
---
b.超时控制中间件
a.功能概述
提供灵活的超时控制机制，防止调用阻塞，保证系统响应性。
b.超时策略
支持全局超时、方法级超时、上下文感知超时等策略。
c.实现示例
---
// TimeoutMiddleware 超时控制中间件
func TimeoutMiddleware(options ...TimeoutOption) Middleware {
config := DefaultTimeoutConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 计算超时时间
timeout := calculateTimeout(ctx, config)
// 如果不需要超时控制，直接执行
if timeout <= 0 {
return handler(ctx, req)
}
// 创建带超时的上下文
ctx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
// 创建结果通道
resultCh := make(chan callResult, 1)
// 异步执行调用
go func() {
resp, err := handler(ctx, req)
resultCh <- callResult{resp: resp, err: err}
}()
// 等待结果或超时
select {
case result := <-resultCh:
return result.resp, result.err
case <-ctx.Done():
return nil, errors.DeadlineExceeded("TIMEOUT",
fmt.Sprintf("request timeout after %v", timeout))
}
}
}
}
// callResult 调用结果
type callResult struct {
resp interface{}
err error
}
// calculateTimeout 计算超时时间
func calculateTimeout(ctx context.Context, config *TimeoutConfig) time.Duration {
// 检查上下文中的剩余时间
if deadline, ok := ctx.Deadline(); ok {
remaining := time.Until(deadline)
if remaining <= 0 {
return 0
}
// 使用剩余时间或配置时间中的较小值
if remaining < config.DefaultTimeout {
return remaining
}
}
// 根据请求类型确定超时时间
method := GetMethod(ctx)
if timeout, exists := config.MethodTimeouts[method]; exists {
return timeout
}
return config.DefaultTimeout
}
---
04.分布式链路追踪中间件
提供完整的分布式链路追踪解决方案，支持多种追踪系统。
a.客户端链路追踪中间件
a.功能概述
在客户端调用时创建和管理追踪Span，实现调用链的完整追踪。
b.追踪能力
自动创建Span、传播追踪上下文、记录调用元数据。
c.实现示例
---
// ClientTracingMiddleware 客户端链路追踪中间件
func ClientTracingMiddleware(tracer opentracing.Tracer, options ...TracingOption) Middleware {
config := DefaultTracingConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
serviceName := getServiceName(ctx)
methodName := getMethodName(ctx)
// 创建客户端 Span
span := tracer.StartSpan(
fmt.Sprintf("%s.%s", serviceName, methodName),
opentracing.Tag{Key: "span.kind", Value: "client"},
opentracing.Tag{Key: "component", Value: "grpc"},
opentracing.Tag{Key: "service.name", Value: serviceName},
opentracing.Tag{Key: "method.name", Value: methodName},
)
defer span.Finish()
// 将 Span 注入到上下文
ctx = opentracing.ContextWithSpan(ctx, span)
// 如果存在父 Span，建立父子关系
if parentSpan := opentracing.SpanFromContext(ctx); parentSpan != nil {
span = tracer.StartSpan(
fmt.Sprintf("%s.%s", serviceName, methodName),
opentracing.ChildOf(parentSpan.Context()),
)
defer span.Finish()
}
// 注入 trace 信息到请求元数据
injectTraceHeaders(ctx, span, config)
// 执行调用
resp, err := handler(ctx, req)
// 记录调用结果
if err != nil {
span.SetTag("error", true)
span.SetTag("error.message", err.Error())
ext.Error.Set(span, true)
} else {
span.SetTag("success", true)
}
return resp, err
}
}
}
// injectTraceHeaders 注入追踪头信息
func injectTraceHeaders(ctx context.Context, span opentracing.Span, config *TracingConfig) {
if config.InjectHeaders {
headers := make(map[string]string)
// 注入 opentracing 头信息
if err := opentracing.GlobalTracer().Inject(
span.Context(),
opentracing.TextMap,
opentracing.TextMapCarrier(headers),
); err != nil {
log.Warnf("failed to inject trace headers: %v", err)
return
}
// 将头信息注入到调用上下文
InjectHeadersToContext(ctx, headers)
}
}
---
b.服务端链路追踪中间件
a.功能概述
在服务端接收请求时处理追踪上下文，继续服务调用链的追踪。
b.上下文处理
提取追踪头信息、创建服务端Span、建立调用关系。
c.实现示例
---
// ServerTracingMiddleware 服务端链路追踪中间件
func ServerTracingMiddleware(tracer opentracing.Tracer, options ...TracingOption) Middleware {
config := DefaultTracingConfig()
for _, opt := range options {
opt(config)
}
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
serviceName := getServiceName(ctx)
methodName := getMethodName(ctx)
// 从请求头中提取 trace 信息
spanCtx, err := extractTraceContext(ctx, tracer)
if err != nil {
log.Warnf("failed to extract trace context: %v", err)
}
// 创建服务端 Span
var span opentracing.Span
if spanCtx != nil {
span = tracer.StartSpan(
fmt.Sprintf("%s.%s", serviceName, methodName),
opentracing.ChildOf(spanCtx),
opentracing.Tag{Key: "span.kind", Value: "server"},
opentracing.Tag{Key: "component", Value: "grpc"},
)
} else {
span = tracer.StartSpan(
fmt.Sprintf("%s.%s", serviceName, methodName),
opentracing.Tag{Key: "span.kind", Value: "server"},
opentracing.Tag{Key: "component", Value: "grpc"},
)
}
defer span.Finish()
// 设置 Span 标签
span.SetTag("service.name", serviceName)
span.SetTag("method.name", methodName)
span.SetTag("peer.address", getPeerAddress(ctx))
// 将 Span 注入到上下文
ctx = opentracing.ContextWithSpan(ctx, span)
// 执行调用
resp, err := handler(ctx, req)
// 记录调用结果
if err != nil {
span.SetTag("error", true)
span.SetTag("error.message", err.Error())
ext.Error.Set(span, true)
} else {
span.SetTag("success", true)
}
return resp, err
}
}
}
// extractTraceContext 提取追踪上下文
func extractTraceContext(ctx context.Context, tracer opentracing.Tracer) (opentracing.SpanContext, error) {
headers := ExtractHeadersFromContext(ctx)
if len(headers) == 0 {
return nil, nil
}
spanCtx, err := tracer.Extract(
opentracing.TextMap,
opentracing.TextMapCarrier(headers),
)
if err != nil {
return nil, err
}
return spanCtx, nil
}
---
05.中间件组合与优化
提供中间件组合和性能优化的最佳实践和实现方案。
a.调用中间件链
a.功能概述
构建完整的客户端中间件链，按照正确的顺序应用各种中间件。
b.链式构建
支持动态添加中间件、依赖管理、顺序控制。
c.实现示例
---
// BuildClientMiddlewareChain 构建客户端中间件链
func BuildClientMiddlewareChain(config *ClientConfig) []Middleware {
var middlewares []Middleware
// 链路追踪中间件
if config.Tracing.Enabled {
middlewares = append(middlewares,
ClientTracingMiddleware(config.Tracing.Tracer),
)
}
// 负载均衡中间件
if config.LoadBalancer.Enabled {
middlewares = append(middlewares,
LoadBalancerMiddleware(config.LoadBalancer.Balancer),
)
}
// 限流中间件
if config.RateLimit.Enabled {
middlewares = append(middlewares,
RateLimitingMiddleware(config.RateLimit.Limiter),
)
}
// 重试中间件
if config.Retry.Enabled {
middlewares = append(middlewares,
RetryMiddleware(config.Retry.Config),
)
}
// 熔断中间件
if config.CircuitBreaker.Enabled {
middlewares = append(middlewares,
CircuitBreakerMiddleware(config.CircuitBreaker.Breaker),
)
}
// 超时中间件
if config.Timeout.Enabled {
middlewares = append(middlewares,
TimeoutMiddleware(config.Timeout.Config),
)
}
return middlewares
}
---
b.性能优化技巧
a.优化原则
中间件顺序优化、异步处理、缓存优化、资源复用等。
b.优化策略
将轻量级中间件放在前面、使用异步处理耗时操作、缓存中间件计算结果。
c.优化示例
---
// OptimizedClientMiddleware 优化的客户端中间件
func OptimizedClientMiddleware(cache Cache, metrics Metrics) Middleware {
return func(handler Handler) Handler {
return func(ctx context.Context, req interface{}) (interface{}, error) {
// 快速缓存检查
cacheKey := generateCacheKey(ctx, req)
if cachedResp, err := cache.Get(ctx, cacheKey); err == nil {
metrics.RecordCacheHit()
return cachedResp, nil
}
// 记录开始时间
start := time.Now()
// 执行调用
resp, err := handler(ctx, req)
// 异步记录指标和缓存
go func() {
duration := time.Since(start)
metrics.RecordCall(duration, err)
if err == nil {
cache.Set(context.Background(), cacheKey, resp, 5*time.Minute)
}
}()
return resp, err
}
}
}
---
6.5 插件化架构设计
01.插件化架构概述
插件化架构是 Kratos 框架的重要特性之一，它允许开发者在不修改核心代码的情况下，通过插件来扩展框架的功能。这种架构设计提供了高度的灵活性和可扩展性，使框架能够适应各种复杂的业务场景。
a.架构设计原则
a.松耦合
插件与核心框架之间通过接口进行交互，降低耦合度。
b.可插拔
插件可以在运行时动态加载和卸载，支持热更新。
c.隔离性
插件之间相互隔离，避免冲突和相互影响。
d.生命周期管理
提供完整的插件生命周期控制，包括初始化、启动、停止、清理等。
e.配置驱动
通过配置文件管理插件，支持灵活的配置和部署。
02.插件系统架构
设计完整的插件系统架构，支持插件的加载、管理和运行。
a.核心组件设计
a.Plugin 插件接口
定义标准的插件接口，确保所有插件的一致性。
b.PluginManager 插件管理器接口
提供插件的统一管理功能，包括加载、卸载、启动、停止等操作。
c.PluginInfo 插件信息
存储插件的基本信息和元数据。
d.PluginStatus 插件状态
管理插件的生命周期状态。
b.插件管理器实现
a.DefaultPluginManager 默认插件管理器实现
提供完整的插件管理功能实现。
b.PluginInstance 插件实例
管理插件的运行时实例和状态信息。
c.ManagerConfig 管理器配置
配置插件管理器的运行参数和行为。
c.实现示例
---
// Plugin 插件接口
type Plugin interface {
// Name 返回插件名称
Name() string
// Version 返回插件版本
Version() string
// Description 返回插件描述
Description() string
// Initialize 初始化插件
Initialize(ctx context.Context, config map[string]interface{}) error
// Start 启动插件
Start(ctx context.Context) error
// Stop 停止插件
Stop(ctx context.Context) error
// Cleanup 清理资源
Cleanup(ctx context.Context) error
// Dependencies 返回插件依赖
Dependencies() []string
}
// PluginManager 插件管理器接口
type PluginManager interface {
// LoadPlugin 加载插件
LoadPlugin(path string) error
// UnloadPlugin 卸载插件
UnloadPlugin(name string) error
// StartPlugin 启动插件
StartPlugin(name string) error
// StopPlugin 停止插件
StopPlugin(name string) error
// GetPlugin 获取插件
GetPlugin(name string) (Plugin, error)
// ListPlugins 列出所有插件
ListPlugins() []PluginInfo
// EnablePlugin 启用插件
EnablePlugin(name string) error
// DisablePlugin 禁用插件
DisablePlugin(name string) error
}
// PluginInfo 插件信息
type PluginInfo struct {
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
Status PluginStatus `json:"status"`
Enabled bool `json:"enabled"`
Config map[string]interface{} `json:"config"`
Metadata map[string]string `json:"metadata"`
}
// PluginStatus 插件状态
type PluginStatus int
const (
PluginStatusUnknown PluginStatus = iota
PluginStatusLoaded
PluginStatusStarted
PluginStatusStopped
PluginStatusError
)
// DefaultPluginManager 默认插件管理器实现
type DefaultPluginManager struct {
mu sync.RWMutex
plugins map[string]PluginInstance
loader PluginLoader
config *ManagerConfig
}
// PluginInstance 插件实例
type PluginInstance struct {
Plugin Plugin
Config map[string]interface{}
Status PluginStatus
LoadedAt time.Time
StartedAt *time.Time
Error error
}
// NewPluginManager 创建插件管理器
func NewPluginManager(config *ManagerConfig) PluginManager {
return &DefaultPluginManager{
plugins: make(map[string]PluginInstance),
loader: NewDefaultPluginLoader(),
config: config,
}
}
// LoadPlugin 加载插件
func (pm *DefaultPluginManager) LoadPlugin(path string) error {
pm.mu.Lock()
defer pm.mu.Unlock()
// 检查插件是否已加载
if info, err := pm.loader.LoadInfo(path); err == nil {
if _, exists := pm.plugins[info.Name]; exists {
return errors.New("plugin already loaded")
}
}
// 加载插件
plugin, config, err := pm.loader.Load(path)
if err != nil {
return fmt.Errorf("failed to load plugin: %v", err)
}
// 验证插件依赖
if err := pm.validateDependencies(plugin); err != nil {
return fmt.Errorf("dependency validation failed: %v", err)
}
// 初始化插件
if err := plugin.Initialize(context.Background(), config); err != nil {
return fmt.Errorf("plugin initialization failed: %v", err)
}
// 注册插件
pm.plugins[plugin.Name()] = PluginInstance{
Plugin: plugin,
Config: config,
Status: PluginStatusLoaded,
LoadedAt: time.Now(),
}
log.Infof("plugin loaded: %s v%s", plugin.Name(), plugin.Version())
return nil
}
// validateDependencies 验证插件依赖
func (pm *DefaultPluginManager) validateDependencies(plugin Plugin) error {
dependencies := plugin.Dependencies()
for _, dep := range dependencies {
if _, exists := pm.plugins[dep]; !exists {
return fmt.Errorf("dependency not found: %s", dep)
}
instance := pm.plugins[dep]
if instance.Status != PluginStatusStarted {
return fmt.Errorf("dependency not started: %s", dep)
}
}
return nil
}
// StartPlugin 启动插件
func (pm *DefaultPluginManager) StartPlugin(name string) error {
pm.mu.Lock()
defer pm.mu.Unlock()
instance, exists := pm.plugins[name]
if !exists {
return errors.New("plugin not found")
}
if instance.Status != PluginStatusLoaded {
return errors.New("plugin not in loaded state")
}
// 启动插件
if err := instance.Plugin.Start(context.Background()); err != nil {
instance.Error = err
instance.Status = PluginStatusError
pm.plugins[name] = instance
return fmt.Errorf("failed to start plugin: %v", err)
}
now := time.Now()
instance.Status = PluginStatusStarted
instance.StartedAt = &now
instance.Error = nil
pm.plugins[name] = instance
log.Infof("plugin started: %s", name)
return nil
}
// StopPlugin 停止插件
func (pm *DefaultPluginManager) StopPlugin(name string) error {
pm.mu.Lock()
defer pm.mu.Unlock()
instance, exists := pm.plugins[name]
if !exists {
return errors.New("plugin not found")
}
if instance.Status != PluginStatusStarted {
return errors.New("plugin not in started state")
}
// 检查是否有其他插件依赖此插件
if err := pm.checkReverseDependencies(name); err != nil {
return err
}
// 停止插件
if err := instance.Plugin.Stop(context.Background()); err != nil {
instance.Error = err
instance.Status = PluginStatusError
pm.plugins[name] = instance
return fmt.Errorf("failed to stop plugin: %v", err)
}
instance.Status = PluginStatusStopped
instance.StartedAt = nil
instance.Error = nil
pm.plugins[name] = instance
log.Infof("plugin stopped: %s", name)
return nil
}
---
03.插件加载机制
提供灵活的插件加载机制，支持多种加载方式和动态加载。
a.动态插件加载器
a.PluginLoader 插件加载器接口
定义标准的插件加载接口，支持不同类型的插件加载。
b.DefaultPluginLoader 默认插件加载器实现
基于 Go plugin 包的动态加载实现。
c.PluginInstance 插件实例管理
管理已加载的插件实例和状态。
b.实现细节
a.符号查找机制
支持 NewPlugin 符号的查找和实例化。
b.插件信息提取
支持插件元数据的提取和验证。
c.错误处理
完善的错误处理和恢复机制。
c.实现示例
---
// PluginLoader 插件加载器接口
type PluginLoader interface {
Load(path string) (Plugin, map[string]interface{}, error)
LoadInfo(path string) (*PluginInfo, error)
Unload(path string) error
}
// DefaultPluginLoader 默认插件加载器实现
type DefaultPluginLoader struct {
mu sync.Mutex
plugins map[string]*plugin.Plugin
instances map[string]interface{}
}
// NewDefaultPluginLoader 创建默认插件加载器
func NewDefaultPluginLoader() PluginLoader {
return &DefaultPluginLoader{
plugins: make(map[string]*plugin.Plugin),
instances: make(map[string]interface{}),
}
}
// Load 加载插件
func (loader *DefaultPluginLoader) Load(path string) (Plugin, map[string]interface{}, error) {
loader.mu.Lock()
defer loader.mu.Unlock()
// 检查插件是否已加载
if plug, exists := loader.plugins[path]; exists {
// 返回已加载的插件实例
instance, exists := loader.instances[path]
if !exists {
return nil, nil, errors.New("plugin loaded but instance not found")
}
plugin, ok := instance.(Plugin)
if !ok {
return nil, nil, errors.New("invalid plugin type")
}
config := getDefaultPluginConfig(plugin)
return plugin, config, nil
}
// 加载 .so 文件
plug, err := plugin.Open(path)
if err != nil {
return nil, nil, fmt.Errorf("failed to open plugin: %v", err)
}
// 查找插件符号
symPlugin, err := plug.Lookup("NewPlugin")
if err != nil {
return nil, nil, fmt.Errorf("plugin symbol not found: %v", err)
}
// 类型断言
newPlugin, ok := symPlugin.(func() Plugin)
if !ok {
return nil, nil, errors.New("invalid plugin signature")
}
// 创建插件实例
instance := newPlugin()
config := getDefaultPluginConfig(instance)
// 缓存插件
loader.plugins[path] = plug
loader.instances[path] = instance
return instance, config, nil
}
// LoadInfo 加载插件信息（不创建实例）
func (loader *DefaultPluginLoader) LoadInfo(path string) (*PluginInfo, error) {
plug, err := plugin.Open(path)
if err != nil {
return nil, fmt.Errorf("failed to open plugin: %v", err)
}
// 查找插件信息符号
symInfo, err := plug.Lookup("PluginInfo")
if err != nil {
return nil, fmt.Errorf("plugin info not found: %v", err)
}
info, ok := symInfo.(*PluginInfo)
if !ok {
return nil, errors.New("invalid plugin info type")
}
return info, nil
}
// getDefaultPluginConfig 获取默认插件配置
func getDefaultPluginConfig(plugin Plugin) map[string]interface{} {
config := make(map[string]interface{})
// 从环境变量加载配置
if pluginConfig := os.Getenv(fmt.Sprintf("PLUGIN_%s_CONFIG", strings.ToUpper(plugin.Name()))); pluginConfig != "" {
if err := json.Unmarshal([]byte(pluginConfig), &config); err != nil {
log.Warnf("failed to parse plugin config: %v", err)
}
}
// 从配置文件加载配置
if configFile := getConfigFile(plugin.Name()); configFile != "" {
if fileConfig, err := loadConfigFromFile(configFile); err == nil {
mergeConfig(config, fileConfig)
} else {
log.Warnf("failed to load plugin config file: %v", err)
}
}
return config
}
---
04.插件配置管理
提供完整的插件配置管理方案，支持多种配置源和动态配置更新。
a.PluginConfig 插件配置管理器
a.配置加载机制
支持从文件、环境变量、远程配置中心加载配置。
b.配置监听机制
支持配置文件变化的监听和热更新。
c.配置验证机制
提供配置的验证和类型检查功能。
b.配置结构设计
a.PluginConfigData 插件配置数据
定义插件配置的数据结构。
b.ConfigWatcher 配置监听器
监听配置文件的变化。
c.配置示例
---
// PluginConfig 插件配置管理器
type PluginConfig struct {
mu sync.RWMutex
configs map[string]*PluginConfigData
watcher ConfigWatcher
}
// PluginConfigData 插件配置数据
type PluginConfigData struct {
Name string `yaml:"name"`
Version string `yaml:"version"`
Enabled bool `yaml:"enabled"`
Config map[string]interface{} `yaml:"config"`
DependsOn []string `yaml:"depends_on"`
Order int `yaml:"order"`
}
// LoadPluginConfig 加载插件配置
func (pc *PluginConfig) LoadPluginConfig(configPath string) error {
pc.mu.Lock()
defer pc.mu.Unlock()
data, err := os.ReadFile(configPath)
if err != nil {
return fmt.Errorf("failed to read config file: %v", err)
}
var configData struct {
Plugins []PluginConfigData `yaml:"plugins"`
}
if err := yaml.Unmarshal(data, &configData); err != nil {
return fmt.Errorf("failed to parse config: %v", err)
}
for _, pluginData := range configData.Plugins {
pc.configs[pluginData.Name] = &pluginData
}
return nil
}
// GetPluginConfig 获取插件配置
func (pc *PluginConfig) GetPluginConfig(name string) (*PluginConfigData, error) {
pc.mu.RLock()
defer pc.mu.RUnlock()
config, exists := pc.configs[name]
if !exists {
return nil, errors.New("plugin config not found")
}
return config, nil
}
// WatchPluginConfig 监听插件配置变化
func (pc *PluginConfig) WatchPluginConfig(configPath string, callback func(*PluginConfigData)) error {
return pc.watcher.Watch(configPath, func(data []byte) {
var configData struct {
Plugins []PluginConfigData `yaml:"plugins"`
}
if err := yaml.Unmarshal(data, &configData); err != nil {
log.Errorf("failed to parse updated config: %v", err)
return
}
pc.mu.Lock()
for _, pluginData := range configData.Plugins {
pc.configs[pluginData.Name] = &pluginData
callback(&pluginData)
}
pc.mu.Unlock()
})
}
---
05.插件类型分类
根据插件的功能和用途，将插件分为不同的类型，提供专门的支持。
a.中间件插件
a.功能概述
提供中间件功能的插件，用于扩展框架的中间件能力。
b.MiddlewarePlugin 中间件插件
实现中间件插件的基本结构和接口。
c.实现示例
---
// MiddlewarePlugin 中间件插件
type MiddlewarePlugin struct {
BasePlugin
middleware Middleware
}
// NewMiddlewarePlugin 创建中间件插件
func NewMiddlewarePlugin(name string, middleware Middleware) *MiddlewarePlugin {
return &MiddlewarePlugin{
BasePlugin: BasePlugin{name: name},
middleware: middleware,
}
}
// Initialize 初始化中间件插件
func (mp *MiddlewarePlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := mp.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 注册中间件到框架
return RegisterMiddleware(mp.name, mp.middleware)
}
// GetMiddleware 获取中间件
func (mp *MiddlewarePlugin) GetMiddleware() Middleware {
return mp.middleware
}
// BasePlugin 基础插件实现
type BasePlugin struct {
name string
version string
config map[string]interface{}
}
func (bp *BasePlugin) Name() string { return bp.name }
func (bp *BasePlugin) Version() string { return bp.version }
func (bp *BasePlugin) Description() string { return "" }
func (bp *BasePlugin) Dependencies() []string { return nil }
func (bp *BasePlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
bp.config = config
return nil
}
func (bp *BasePlugin) Start(ctx context.Context) error { return nil }
func (bp *BasePlugin) Stop(ctx context.Context) error { return nil }
func (bp *BasePlugin) Cleanup(ctx context.Context) error { return nil }
---
b.服务插件
a.功能概述
提供服务功能的插件，用于扩展框架的服务能力。
b.ServicePlugin 服务插件
实现服务插件的基本结构和接口。
c.实现示例
---
// ServicePlugin 服务插件
type ServicePlugin struct {
BasePlugin
service Service
}
// Service 服务接口
type Service interface {
Name() string
Register(server interface{}) error
Deregister(server interface{}) error
}
// NewServicePlugin 创建服务插件
func NewServicePlugin(name string, service Service) *ServicePlugin {
return &ServicePlugin{
BasePlugin: BasePlugin{name: name},
service: service,
}
}
// Initialize 初始化服务插件
func (sp *ServicePlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := sp.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 初始化服务
if initializer, ok := sp.service.(ServiceInitializer); ok {
return initializer.Initialize(ctx, config)
}
return nil
}
// Start 启动服务插件
func (sp *ServicePlugin) Start(ctx context.Context) error {
// 注册服务到服务器
server := GetServer()
return sp.service.Register(server)
}
// Stop 停止服务插件
func (sp *ServicePlugin) Stop(ctx context.Context) error {
// 从服务器注销服务
server := GetServer()
return sp.service.Deregister(server)
}
// ServiceInitializer 服务初始化器接口
type ServiceInitializer interface {
Initialize(ctx context.Context, config map[string]interface{}) error
}
---
c.工具插件
a.功能概述
提供各种工具功能的插件，用于扩展框架的工具能力。
b.UtilityPlugin 工具插件
实现工具插件的基本结构和接口。
c.实现示例
---
// UtilityPlugin 工具插件
type UtilityPlugin struct {
BasePlugin
utilities map[string]interface{}
}
// NewUtilityPlugin 创建工具插件
func NewUtilityPlugin(name string, utilities map[string]interface{}) *UtilityPlugin {
return &UtilityPlugin{
BasePlugin: BasePlugin{name: name},
utilities: utilities,
}
}
// Initialize 初始化工具插件
func (up *UtilityPlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := up.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 注册工具到全局工具箱
for name, util := range up.utilities {
RegisterUtility(name, util)
}
return nil
}
// GetUtility 获取工具
func (up *UtilityPlugin) GetUtility(name string) (interface{}, bool) {
util, exists := up.utilities[name]
return util, exists
}
// RegisterUtility 注册工具
func RegisterUtility(name string, utility interface{}) {
globalUtilities[name] = utility
}
var globalUtilities = make(map[string]interface{})
---
06.插件生命周期管理
提供完整的插件生命周期管理，确保插件的正确运行和资源清理。
a.PluginLifecycle 插件生命周期管理器
a.状态机设计
实现插件状态的转换管理和验证。
b.LifecycleListener 生命周期监听器
支持插件生命周期事件的监听和处理。
c.状态转换规则
定义插件状态转换的规则和约束。
b.实现示例
---
// PluginLifecycle 插件生命周期管理器
type PluginLifecycle struct {
mu sync.RWMutex
states map[string]PluginState
listeners map[string][]LifecycleListener
}
// PluginState 插件状态
type PluginState struct {
Plugin string
Status PluginStatus
Timestamp time.Time
Error error
Metadata map[string]interface{}
}
// LifecycleListener 生命周期监听器接口
type LifecycleListener interface {
OnStateChanged(pluginName string, from, to PluginStatus, err error)
OnPluginLoaded(pluginName string)
OnPluginStarted(pluginName string)
OnPluginStopped(pluginName string)
OnPluginUnloaded(pluginName string)
}
// NewPluginLifecycle 创建插件生命周期管理器
func NewPluginLifecycle() *PluginLifecycle {
return &PluginLifecycle{
states: make(map[string]PluginState),
listeners: make(map[string][]LifecycleListener),
}
}
// TransitionState 状态转换
func (pl *PluginLifecycle) TransitionState(pluginName string, to PluginStatus, err error) {
pl.mu.Lock()
defer pl.mu.Unlock()
from := PluginStatusUnknown
if state, exists := pl.states[pluginName]; exists {
from = state.Status
}
// 验证状态转换是否合法
if !pl.isValidTransition(from, to) {
log.Warnf("invalid state transition for plugin %s: %s -> %s", pluginName, from, to)
return
}
// 更新状态
pl.states[pluginName] = PluginState{
Plugin: pluginName,
Status: to,
Timestamp: time.Now(),
Error: err,
}
// 通知监听器
pl.notifyListeners(pluginName, from, to, err)
// 记录状态变化
log.Infof("plugin %s state transition: %s -> %s", pluginName, from, to)
}
// isValidTransition 验证状态转换是否合法
func (pl *PluginLifecycle) isValidTransition(from, to PluginStatus) bool {
validTransitions := map[PluginStatus][]PluginStatus{
PluginStatusUnknown: {PluginStatusLoaded},
PluginStatusLoaded: {PluginStatusStarted, PluginStatusError},
PluginStatusStarted: {PluginStatusStopped, PluginStatusError},
PluginStatusStopped: {PluginStatusStarted, PluginStatusUnknown},
PluginStatusError: {PluginStatusLoaded, PluginStatusStopped},
}
allowed, exists := validTransitions[from]
if !exists {
return false
}
for _, status := range allowed {
if status == to {
return true
}
}
return false
}
// AddListener 添加生命周期监听器
func (pl *PluginLifecycle) AddListener(pluginName string, listener LifecycleListener) {
pl.mu.Lock()
defer pl.mu.Unlock()
if pl.listeners[pluginName] == nil {
pl.listeners[pluginName] = make([]LifecycleListener, 0)
}
pl.listeners[pluginName] = append(pl.listeners[pluginName], listener)
}
// notifyListeners 通知监听器
func (pl *PluginLifecycle) notifyListeners(pluginName string, from, to PluginStatus, err error) {
listeners := pl.listeners[pluginName]
for _, listener := range listeners {
listener.OnStateChanged(pluginName, from, to, err)
switch to {
case PluginStatusLoaded:
listener.OnPluginLoaded(pluginName)
case PluginStatusStarted:
listener.OnPluginStarted(pluginName)
case PluginStatusStopped:
listener.OnPluginStopped(pluginName)
}
}
}
---
6.6 第三方插件集成
01.第三方插件集成概述
Kratos框架具有良好的开放性，支持集成各种第三方插件来扩展功能。这些插件可以来自开源社区、商业供应商或企业内部开发，为框架提供额外的能力支持。
a.插件集成模式
a.直接集成
将第三方插件直接嵌入到应用中，简单直接但灵活性较低。
b.适配器模式
通过适配器将第三方插件转换为Kratos插件接口，灵活性高。
c.代理模式
通过代理服务调用第三方插件功能，支持远程调用。
d.事件驱动
通过事件机制集成第三方插件，松耦合设计。
b.适配器接口规范
a.PluginAdapter 插件适配器接口
定义标准的适配器接口，确保适配器的一致性。
b.CanAdapt 支持检查
检查适配器是否支持特定插件的适配。
c.GetSupportedTypes 支持类型
返回适配器支持的插件类型列表。
c.ThirdPartyPlugin 第三方插件适配器基类
a.功能概述
提供第三方插件适配器的基础实现，简化适配器的开发。
b.实现细节
支持配置管理、错误处理、生命周期管理等。
c.实现示例
---
// PluginAdapter 插件适配器接口
type PluginAdapter interface {
// Adapt 将第三方插件适配为 Kratos 插件
Adapt(plugin interface{}) (Plugin, error)
// CanAdapt 检查是否可以适配指定插件
CanAdapt(plugin interface{}) bool
// GetSupportedTypes 获取支持的插件类型
GetSupportedTypes() []string
}
// ThirdPartyPlugin 第三方插件适配器基类
type ThirdPartyPlugin struct {
BasePlugin
originalPlugin interface{}
adapter PluginAdapter
}
// NewThirdPartyPlugin 创建第三方插件
func NewThirdPartyPlugin(originalPlugin interface{}, adapter PluginAdapter) (*ThirdPartyPlugin, error) {
if !adapter.CanAdapt(originalPlugin) {
return nil, errors.New("plugin type not supported by adapter")
}
kratosPlugin, err := adapter.Adapt(originalPlugin)
if err != nil {
return nil, fmt.Errorf("failed to adapt plugin: %v", err)
}
return &ThirdPartyPlugin{
BasePlugin: BasePlugin{},
originalPlugin: originalPlugin,
adapter: adapter,
Plugin: kratosPlugin,
}, nil
}
---
02.适配器注册器
提供适配器的注册和管理功能，支持多种适配器的统一管理。
a.AdapterRegistry 适配器注册器
a.功能概述
管理所有适配器的注册、查找和使用。
b.AdapterRegistry 适配器注册器实现
提供完整的适配器管理功能。
c.PluginDetector 插件检测器
自动检测插件类型，简化适配过程。
b.实现细节
a.注册机制
支持适配器的动态注册和注销。
b.检测机制
基于反射和元数据的插件类型检测。
c.适配流程
自动化的插件适配流程。
c.实现示例
---
// AdapterRegistry 适配器注册器
type AdapterRegistry struct {
mu sync.RWMutex
adapters map[string]PluginAdapter
detectors []PluginDetector
}
// PluginDetector 插件检测器接口
type PluginDetector interface {
// Detect 检测插件类型
Detect(plugin interface{}) (string, error)
// GetPriority 获取检测器优先级
GetPriority() int
}
// NewAdapterRegistry 创建适配器注册器
func NewAdapterRegistry() *AdapterRegistry {
registry := &AdapterRegistry{
adapters: make(map[string]PluginAdapter),
detectors: make([]PluginDetector, 0),
}
// 注册内置适配器
registry.RegisterBuiltinAdapters()
return registry
}
// RegisterAdapter 注册适配器
func (ar *AdapterRegistry) RegisterAdapter(pluginType string, adapter PluginAdapter) {
ar.mu.Lock()
defer ar.mu.Unlock()
ar.adapters[pluginType] = adapter
}
// RegisterDetector 注册检测器
func (ar *AdapterRegistry) RegisterDetector(detector PluginDetector) {
ar.mu.Lock()
defer ar.mu.Unlock()
ar.detectors = append(ar.detectors, detector)
// 按优先级排序
sort.Slice(ar.detectors, func(i, j int) bool {
return ar.detectors[i].GetPriority() > ar.detectors[j].GetPriority()
})
}
// AdaptPlugin 适配插件
func (ar *AdapterRegistry) AdaptPlugin(plugin interface{}) (Plugin, error) {
// 检测插件类型
pluginType, err := ar.detectPluginType(plugin)
if err != nil {
return nil, fmt.Errorf("failed to detect plugin type: %v", err)
}
// 获取适配器
ar.mu.RLock()
adapter, exists := ar.adapters[pluginType]
ar.mu.RUnlock()
if !exists {
return nil, fmt.Errorf("no adapter found for plugin type: %s", pluginType)
}
// 执行适配
return adapter.Adapt(plugin)
}
// detectPluginType 检测插件类型
func (ar *AdapterRegistry) detectPluginType(plugin interface{}) (string, error) {
ar.mu.RLock()
defer ar.mu.RUnlock()
for _, detector := range ar.detectors {
if pluginType, err := detector.Detect(plugin); err == nil {
return pluginType, nil
}
}
return "", errors.New("unable to detect plugin type")
}
---
03.常见第三方插件适配器
提供常见第三方插件的适配器实现，简化集成过程。
a.gRPC 中间件适配器
a.功能概述
将 gRPC 中间件适配为 Kratos 插件，扩展框架的 gRPC 支持。
b.GRPCMiddlewareAdapter gRPC 中间件适配器
实现 gRPC 中间件的标准适配器。
c.实现示例
---
// GRPCMiddlewareAdapter gRPC 中间件适配器
type GRPCMiddlewareAdapter struct{}
// Adapt 适配 gRPC 中间件
func (g *GRPCMiddlewareAdapter) Adapt(plugin interface{}) (Plugin, error) {
grpcMiddleware, ok := plugin.(grpc.UnaryServerInterceptor)
if !ok {
return nil, errors.New("plugin is not a gRPC unary server interceptor")
}
return &GRPCMiddlewarePlugin{
name: "grpc-middleware",
version: "1.0.0",
interceptor: grpcMiddleware,
}, nil
}
// CanAdapt 检查是否可以适配
func (g *GRPCMiddlewareAdapter) CanAdapt(plugin interface{}) bool {
_, ok := plugin.(grpc.UnaryServerInterceptor)
return ok
}
// GetSupportedTypes 获取支持的插件类型
func (g *GRPCMiddlewareAdapter) GetSupportedTypes() []string {
return []string{"grpc.UnaryServerInterceptor", "grpc.StreamServerInterceptor"}
}
// GRPCMiddlewarePlugin gRPC 中间件插件
type GRPCMiddlewarePlugin struct {
BasePlugin
name string
version string
interceptor grpc.UnaryServerInterceptor
}
// Name 返回插件名称
func (gp *GRPCMiddlewarePlugin) Name() string {
return gp.name
}
// Version 返回插件版本
func (gp *GRPCMiddlewarePlugin) Version() string {
return gp.version
}
// Initialize 初始化插件
func (gp *GRPCMiddlewarePlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := gp.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 注册 gRPC 中间件到 Kratos 服务器
return RegisterGRPCMiddleware(gp.interceptor)
}
// RegisterGRPCMiddleware 注册 gRPC 中间件
func RegisterGRPCMiddleware(interceptor grpc.UnaryServerInterceptor) error {
server := GetGRPCServer()
if server == nil {
return errors.New("gRPC server not found")
}
// 包装原有的 gRPC 服务器
originalServer := server
server = &grpcServerWrapper{
original: originalServer,
interceptor: interceptor,
}
return nil
}
// grpcServerWrapper gRPC 服务器包装器
type grpcServerWrapper struct {
original interface{}
interceptor grpc.UnaryServerInterceptor
}
---
b.HTTP 中间件适配器
a.功能概述
将 HTTP 中间件适配为 Kratos 插件，扩展框架的 HTTP 支持。
b.HTTPMiddlewareAdapter HTTP 中间件适配器
实现 HTTP 中间件的标准适配器。
c.实现示例
---
// HTTPMiddlewareAdapter HTTP 中间件适配器
type HTTPMiddlewareAdapter struct{}
// Adapt 适配 HTTP 中间件
func (h *HTTPMiddlewareAdapter) Adapt(plugin interface{}) (Plugin, error) {
var httpMiddleware func(http.Handler) http.Handler
switch p := plugin.(type) {
case func(http.Handler) http.Handler:
httpMiddleware = p
case http.Handler:
httpMiddleware = func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
p.ServeHTTP(w, r)
next.ServeHTTP(w, r)
})
}
case http.HandlerFunc:
httpMiddleware = func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
p(w, r)
next.ServeHTTP(w, r)
})
}
default:
return nil, errors.New("unsupported HTTP middleware type")
}
return &HTTPMiddlewarePlugin{
name: "http-middleware",
version: "1.0.0",
middleware: httpMiddleware,
}, nil
}
// CanAdapt 检查是否可以适配
func (h *HTTPMiddlewareAdapter) CanAdapt(plugin interface{}) bool {
switch plugin.(type) {
case func(http.Handler) http.Handler:
return true
case http.Handler:
return true
case http.HandlerFunc:
return true
default:
return false
}
}
// GetSupportedTypes 获取支持的插件类型
func (h *HTTPMiddlewareAdapter) GetSupportedTypes() []string {
return []string{
"func(http.Handler) http.Handler",
"http.Handler",
"http.HandlerFunc",
}
}
// HTTPMiddlewarePlugin HTTP 中间件插件
type HTTPMiddlewarePlugin struct {
BasePlugin
name string
version string
middleware func(http.Handler) http.Handler
}
// Initialize 初始化插件
func (hp *HTTPMiddlewarePlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := hp.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 注册 HTTP 中间件到 Kratos 服务器
return RegisterHTTPMiddleware(hp.middleware)
}
// RegisterHTTPMiddleware 注册 HTTP 中间件
func RegisterHTTPMiddleware(middleware func(http.Handler) http.Handler) error {
server := GetHTTPServer()
if server == nil {
return errors.New("HTTP server not found")
}
// 将中间件添加到服务器中间件链
return server.Use(middleware)
}
---
c.Prometheus 指标适配器
a.功能概述
将 Prometheus 指标收集器适配为 Kratos 插件，扩展框架的监控支持。
b.PrometheusAdapter Prometheus 指标适配器
实现 Prometheus 指标收集器的标准适配器。
c.实现示例
---
// PrometheusAdapter Prometheus 指标适配器
type PrometheusAdapter struct{}
// Adapt 适配 Prometheus 指标收集器
func (p *PrometheusAdapter) Adapt(plugin interface{}) (Plugin, error) {
var collector prometheus.Collector
switch pl := plugin.(type) {
case prometheus.Collector:
collector = pl
case prometheus.Gatherer:
// 将 Gatherer 转换为 Collector
collector = &gathererToCollectorAdapter{gatherer: pl}
default:
return nil, errors.New("plugin is not a Prometheus collector or gatherer")
}
return &PrometheusPlugin{
name: "prometheus-collector",
version: "1.0.0",
collector: collector,
}, nil
}
// CanAdapt 检查是否可以适配
func (p *PrometheusAdapter) CanAdapt(plugin interface{}) bool {
_, ok := plugin.(prometheus.Collector)
if ok {
return true
}
_, ok = plugin.(prometheus.Gatherer)
return ok
}
// GetSupportedTypes 获取支持的插件类型
func (p *PrometheusAdapter) GetSupportedTypes() []string {
return []string{
"prometheus.Collector",
"prometheus.Gatherer",
"*prometheus.Registry",
}
}
// PrometheusPlugin Prometheus 插件
type PrometheusPlugin struct {
BasePlugin
name string
version string
collector prometheus.Collector
}
// Initialize 初始化插件
func (pp *PrometheusPlugin) Initialize(ctx context.Context, config map[string]interface{}) error {
if err := pp.BasePlugin.Initialize(ctx, config); err != nil {
return err
}
// 注册 Prometheus 指标
return prometheus.MustRegister(pp.collector)
}
// Cleanup 清理资源
func (pp *PrometheusPlugin) Cleanup(ctx context.Context) error {
prometheus.Unregister(pp.collector)
return pp.BasePlugin.Cleanup(ctx)
}
// gathererToCollectorAdapter Gatherer 到 Collector 适配器
type gathererToCollectorAdapter struct {
gatherer prometheus.Gatherer
}
func (g *gathererToCollectorAdapter) Describe(ch chan<- *prometheus.Desc) {
// 空实现，因为 Gatherer 不提供描述信息
}
func (g *gathererToCollectorAdapter) Collect(ch chan<- prometheus.Metric) {
metricFamilies, err := g.gatherer.Gather()
if err != nil {
log.Errorf("failed to gather metrics: %v", err)
return
}
for _, family := range metricFamilies {
for _, metric := range family.Metric {
// 将 Prometheus MetricFamily 转换为 Metric
if promMetric, err := convertMetric(family, metric); err == nil {
ch <- promMetric
}
}
}
}
// convertMetric 转换 Metric
func convertMetric(family *dto.MetricFamily, metric *dto.Metric) (prometheus.Metric, error) {
// 实现转换逻辑
// 这里省略具体的转换实现
return nil, nil
}
---
d.插件检测器实现
a.ReflectionDetector 反射检测器
a.功能概述
基于反射机制自动检测插件类型，简化适配过程。
b.实现细节
通过类型断言和接口检查来确定插件类型。
b.实现示例
---
// ReflectionDetector 反射检测器
type ReflectionDetector struct {
priority int
}
// NewReflectionDetector 创建反射检测器
func NewReflectionDetector() *ReflectionDetector {
return &ReflectionDetector{priority: 1}
}
// Detect 检测插件类型
func (r *ReflectionDetector) Detect(plugin interface{}) (string, error) {
pluginType := reflect.TypeOf(plugin)
// 检查是否实现了 gRPC 中间件接口
if r.implementsGRPCMiddleware(pluginType) {
return "grpc-middleware", nil
}
// 检查是否实现了 HTTP 中间件接口
if r.implementsHTTPMiddleware(pluginType) {
return "http-middleware", nil
}
// 检查是否实现了 Prometheus Collector 接口
if r.implementsPrometheusCollector(pluginType) {
return "prometheus-collector", nil
}
return "", errors.New("plugin type not detected")
}
// GetPriority 获取检测器优先级
func (r *ReflectionDetector) GetPriority() int {
return r.priority
}
// implementsGRPCMiddleware 检查是否实现了 gRPC 中间件接口
func (r *ReflectionDetector) implementsGRPCMiddleware(t reflect.Type) bool {
grpcInterceptorType := reflect.TypeOf((*grpc.UnaryServerInterceptor)(nil)).Elem()
return t.Implements(grpcInterceptorType)
}
// implementsHTTPMiddleware 检查是否实现了 HTTP 中间件接口
func (r *ReflectionDetector) implementsHTTPMiddleware(t reflect.Type) bool {
httpHandlerType := reflect.TypeOf((func(http.Handler) http.Handler)(nil))
return t.ConvertibleTo(httpHandlerType)
}
// implementsPrometheusCollector 检查是否实现了 Prometheus Collector 接口
func (r *ReflectionDetector) implementsPrometheusCollector(t reflect.Type) bool {
collectorType := reflect.TypeOf((*prometheus.Collector)(nil)).Elem()
return t.Implements(collectorType)
}
---
b.MetadataDetector 元数据检测器
a.功能概述
基于插件元数据自动检测插件类型，提供更精确的类型检测。
b.实现细节
通过插件标签、描述信息等元数据来确定插件类型。
c.实现示例
---
// MetadataDetector 元数据检测器
type MetadataDetector struct {
priority int
}
// NewMetadataDetector 创建元数据检测器
func NewMetadataDetector() *MetadataDetector {
return &MetadataDetector{priority: 2}
}
// Detect 检测插件类型
func (m *MetadataDetector) Detect(plugin interface{}) (string, error) {
// 检查是否有 GetPluginInfo 方法
if getPluginInfoMethod := reflect.ValueOf(plugin).MethodByName("GetPluginInfo"); getPluginInfoMethod.IsValid() {
results := getPluginInfoMethod.Call(nil)
if len(results) > 0 {
if info, ok := results[0].Interface().(map[string]interface{}); ok {
if pluginType, exists := info["type"]; exists {
if typeStr, ok := pluginType.(string); ok {
return typeStr, nil
}
}
}
}
}
// 检查是否有 PluginMetadata 标签
if metadata := m.extractPluginMetadata(plugin); metadata != nil {
return metadata.Type, nil
}
return "", errors.New("plugin metadata not found")
}
// GetPriority 获取检测器优先级
func (m *MetadataDetector) GetPriority() int {
return m.priority
}
// extractPluginMetadata 提取插件元数据
func (m *MetadataDetector) extractPluginMetadata(plugin interface{}) *PluginMetadata {
t := reflect.TypeOf(plugin)
// 检查结构体字段
if t.Kind() == reflect.Struct {
for i := 0; i < t.NumField(); i++ {
field := t.Field(i)
if metadata, ok := field.Tag.Lookup("plugin"); ok {
return m.parsePluginMetadata(metadata)
}
}
}
// 检查类型标签
if metadata, ok := t.TagLookup("plugin"); ok {
return m.parsePluginMetadata(metadata)
}
return nil
}
// parsePluginMetadata 解析插件元数据
func (m *MetadataDetector) parsePluginMetadata(metadata string) *PluginMetadata {
var pm PluginMetadata
if err := json.Unmarshal([]byte(metadata), &pm); err != nil {
return nil
}
return &pm
}
// PluginMetadata 插件元数据
type PluginMetadata struct {
Type string `json:"type"`
Name string `json:"name"`
Version string `json:"version"`
Description string `json:"description"`
Author string `json:"author"`
License string `json:"license"`
Homepage string `json:"homepage"`
Tags []string `json:"tags"`
Dependencies []string `json:"dependencies"`
Config map[string]interface{} `json:"config"`
}
---
04.插件集成配置
提供完整的插件集成配置方案，支持多种配置方式和部署策略。
a.插件配置文件
a.配置文件格式
支持 YAML 格式的插件配置文件，包含插件的详细配置。
b.配置结构
定义插件配置的层次结构和组织方式。
c.配置示例
---
# plugin-integration.yaml
plugins:
# gRPC 中间件插件
grpc-middleware:
enabled: true
type: "grpc-middleware"
source:
type: "shared_library"
path: "/plugins/grpc_interceptor.so"
symbol: "NewGRPCInterceptor"
config:
timeout: 30s
retry_attempts: 3
# HTTP 中间件插件
http-middleware:
enabled: true
type: "http-middleware"
source:
type: "go_package"
package: "github.com/auth0/go-jwt-middleware"
function: "New"
config:
secret_key: "${JWT_SECRET}"
skip_paths: ["/health", "/metrics"]
# Prometheus 指标插件
prometheus-metrics:
enabled: true
type: "prometheus-collector"
source:
type: "go_package"
package: "github.com/prometheus/client_golang/prometheus"
function: "NewGaugeVec"
config:
namespace: "kratos"
subsystem: "server"
name: "requests_total"
help: "Total number of requests"
# 数据库插件
database-middleware:
enabled: true
type: "database-middleware"
source:
type: "shared_library"
path: "/plugins/database_interceptor.so"
symbol: "NewDatabaseInterceptor"
config:
driver: "mysql"
dsn: "${DATABASE_DSN}"
max_connections: 100
# 适配器配置
adapters:
grpc-middleware:
adapter_type: "GRPCMiddlewareAdapter"
config:
enable_validation: true
http-middleware:
adapter_type: "HTTPMiddlewareAdapter"
config:
enable_cors: true
enable_recovery: true
prometheus-collector:
adapter_type: "PrometheusAdapter"
config:
auto_register: true
namespace_prefix: "kratos"
# 检测器配置
detectors:
- type: "ReflectionDetector"
priority: 1
enabled: true
- type: "MetadataDetector"
priority: 2
enabled: true
- type: "FilenameDetector"
priority: 3
enabled: true
patterns:
- "*_middleware.so"
- "*_interceptor.so"
- "*_collector.so"
---
b.插件集成器
a.PluginIntegrator 插件集成器
提供完整的插件集成流程和管理功能。
b.实现细节
支持插件加载、适配、配置管理、依赖处理等。
c.实现示例
---
// PluginIntegrator 插件集成器
type PluginIntegrator struct {
registry *AdapterRegistry
config *IntegrationConfig
loader PluginLoader
logger log.Logger
}
// IntegrationConfig 集成配置
type IntegrationConfig struct {
Plugins map[string]PluginConfig `yaml:"plugins"`
Adapters map[string]AdapterConfig `yaml:"adapters"`
Detectors []DetectorConfig `yaml:"detectors"`
}
// PluginConfig 插件配置
type PluginConfig struct {
Enabled bool `yaml:"enabled"`
Type string `yaml:"type"`
Source SourceConfig `yaml:"source"`
Config map[string]interface{} `yaml:"config"`
}
// NewPluginIntegrator 创建插件集成器
func NewPluginIntegrator(config *IntegrationConfig, logger log.Logger) *PluginIntegrator {
registry := NewAdapterRegistry()
integrator := &PluginIntegrator{
registry: registry,
config: config,
loader: NewDefaultPluginLoader(),
logger: logger,
}
// 初始化适配器
integrator.initializeAdapters()
// 初始化检测器
integrator.initializeDetectors()
return integrator
}
// IntegratePlugins 集成插件
func (pi *PluginIntegrator) IntegratePlugins(ctx context.Context) error {
for name, pluginConfig := range pi.config.Plugins {
if !pluginConfig.Enabled {
continue
}
if err := pi.integratePlugin(ctx, name, pluginConfig); err != nil {
_ = log.WithContext(ctx, pi.logger).Errorw(
"failed to integrate plugin",
"plugin", name,
"error", err.Error(),
)
continue
}
_ = log.WithContext(ctx, pi.logger).Infow(
"plugin integrated successfully",
"plugin", name,
"type", pluginConfig.Type,
)
}
return nil
}
// integratePlugin 集成单个插件
func (pi *PluginIntegrator) integratePlugin(ctx context.Context, name string, config PluginConfig) error {
// 加载插件
plugin, err := pi.loadPlugin(config)
if err != nil {
return fmt.Errorf("failed to load plugin: %v", err)
}
// 适配插件
kratosPlugin, err := pi.registry.AdaptPlugin(plugin)
if err != nil {
return fmt.Errorf("failed to adapt plugin: %v", err)
}
// 初始化插件
if err := kratosPlugin.Initialize(ctx, config.Config); err != nil {
return fmt.Errorf("failed to initialize plugin: %v", err)
}
// 注册插件到插件管理器
manager := GetPluginManager()
return manager.LoadPluginInstance(name, kratosPlugin)
}
// loadPlugin 加载插件
func (pi *PluginIntegrator) loadPlugin(config PluginConfig) (interface{}, error) {
switch config.Source.Type {
case "shared_library":
return pi.loadSharedLibrary(config.Source)
case "go_package":
return pi.loadGoPackage(config.Source)
case "remote_service":
return pi.loadRemoteService(config.Source)
default:
return nil, fmt.Errorf("unsupported plugin source type: %s", config.Source.Type)
}
}
// loadSharedLibrary 加载共享库插件
func (pi *PluginIntegrator) loadSharedLibrary(source SourceConfig) (interface{}, error) {
// 使用 plugin 包加载 .so 文件
plug, err := plugin.Open(source.Path)
if err != nil {
return nil, fmt.Errorf("failed to open shared library: %v", err)
}
// 查找符号
symbol, err := plug.Lookup(source.Symbol)
if err != nil {
return nil, fmt.Errorf("symbol not found: %v", err)
}
return symbol, nil
}
---