# APIResilience **Repository Path**: vipkwds/apiresilience ## Basic Information - **Project Name**: APIResilience - **Description**: Remote API Resilience 是一个 Go 语言库，用于远程接口响应结构变化的容灾适配 - **Primary Language**: Go - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-12 - **Last Updated**: 2026-06-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Remote API Resilience - Go Library ## 项目概览 Remote API Resilience 是一个 Go 语言库，用于远程接口响应结构变化的容灾适配。 ### 核心功能 1. **配置驱动适配** - 通过 JSON/YAML 配置映射规则，无需改代码 2. **多存储后端** - 支持 GoMemory（进程内）、MySQL、Redis 3. **安全解析引擎** - 防御性提取 + 类型转换 + 字段脱敏 4. **流量录制与回放** - 支持本地 FS、S3、OSS、COS、MinIO 5. **自动化版本探测** - Schema 提取 + Diff + 映射生成 6. **Web 管理界面** - 内嵌 UI + 引导模式 7. **框架集成** - Gin、Echo、Beego 中间件 ## 目录结构 ``` apiresilience/ ├── core/ # 核心库 │ ├── adapter/ # 适配引擎 │ │ ├── path_extractor.go # 路径提取器 │ │ ├── converter.go # 类型转换器 │ │ ├── dynamic.go # 动态适配器 │ │ └── fallback.go # 降级策略 │ ├── driver/ # 存储驱动 │ │ ├── interface.go # 驱动接口 │ │ ├── go_memory.go # 内存存储 │ │ ├── mysql.go # MySQL存储 │ │ ├── redis.go # Redis存储 │ │ └── factory.go # 驱动工厂 │ ├── model/ # 数据模型 │ │ ├── api_config.go # API配置 │ │ ├── mapping.go # 字段映射 │ │ ├── event.go # 事件模型 │ │ └── errors.go # 错误定义 │ ├── recorder/ # 流量录制 │ │ ├── recorder.go # 录制器 │ │ ├── replay.go # 回放器 │ │ └── storage/ # 存储后端 │ │ ├── local_fs.go # 本地文件系统 │ │ ├── s3.go # AWS S3 │ │ ├── oss.go # 阿里云OSS │ │ ├── cos.go # 腾讯云COS │ │ └── minio.go # MinIO │ ├── probe/ # 自动探测 │ │ ├── schema.go # Schema提取 │ │ ├── diff.go # 差异对比 │ │ ├── generator.go # 映射生成 │ │ └── scheduler.go # 定时调度 │ ├── ui/ # 管理界面 │ │ ├── embed.go # 静态资源嵌入 │ │ ├── handler.go # HTTP处理器 │ │ └── wizard.go # 引导模式 │ ├── config_manager.go # 配置管理器 │ ├── lifecycle.go # 生命周期管理 │ ├── metrics.go # 指标收集 │ ├── auth.go # 鉴权机制 │ ├── resilience.go # 主入口 │ └── exports.go # 导出类型 ├── integration/ # 框架集成 │ ├── gin/ # Gin中间件 │ ├── echo/ # Echo中间件 │ └── beego/ # Beego中间件 ├── examples/ # 使用示例 │ ├── gin-demo/ # Gin示例 │ ├── echo-demo/ # Echo示例 │ └── beego-demo/ # Beego示例 └── migrations/ # 数据库迁移 └── 001_init.sql ``` ## 构建与测试命令 ```bash # 安装依赖 go mod tidy # 编译检查 go build ./... # 静态分析 go vet ./... # 运行测试 go test ./... # 运行示例（Gin） go run ./examples/gin-demo/main.go # 运行示例（Echo） go run ./examples/echo-demo/main.go # 运行示例（Beego） go run ./examples/beego-demo/main.go ``` ## 快速开始 ### 安装 ```bash go get gitee.com/vipkwds/apiresilience ``` ### 基础使用 ```go package main import ( "gitee.com/vipkwds/apiresilience/core" ) func main() { // 创建字段映射 mappings := []core.FieldMapping{ { RemotePath: "data.user_name", LocalField: "data.name", FieldType: "string", Required: false, }, } // 创建动态适配器 adapter := core.NewDynamicAdapter(1, 100, true, mappings) // 适配响应数据 jsonData := []byte(`{"code":0,"data":{"user_name":"test"}}`) result, err := adapter.AdaptToMap(jsonData) // result = {"code":0,"data":{"name":"test"}} } ``` ### Gin 集成 ```go package main import ( "github.com/gin-gonic/gin" "gitee.com/vipkwds/apiresilience/core" ginIntegration "gitee.com/vipkwds/apiresilience/integration/gin" ) func main() { adapter := core.NewDynamicAdapter(1, 100, true, mappings) middleware := ginIntegration.NewMiddleware(adapter, &ginIntegration.MiddlewareConfig{ IncludePaths: []string{"/api"}, }) r := gin.Default() r.Use(middleware.Handler()) r.Run(":8080") } ``` ### Echo 集成 ```go package main import ( "github.com/labstack/echo/v4" "gitee.com/vipkwds/apiresilience/core" echoIntegration "gitee.com/vipkwds/apiresilience/integration/echo" ) func main() { adapter := core.NewDynamicAdapter(1, 100, true, mappings) middleware := echoIntegration.NewMiddleware(adapter, &echoIntegration.MiddlewareConfig{ IncludePaths: []string{"/api"}, }) e := echo.New() e.Use(middleware.Handler()) e.Start(":8080") } ``` ## 核心模块说明 ### 1. DynamicAdapter（动态适配器） 核心适配引擎，负责字段映射和类型转换。 ```go type DynamicAdapter struct { Version int Priority int Enable bool Mappings []FieldMapping } // 方法 func NewDynamicAdapter(version, priority int, enable bool, mappings []FieldMapping) *DynamicAdapter func (da *DynamicAdapter) AdaptToMap(body []byte) (map[string]interface{}, error) func (da *DynamicAdapter) AdaptBytes(body []byte) ([]byte, error) ``` ### 2. ConfigManager（配置管理器） 管理 API 配置和版本映射。 ```go func NewConfigManager(driver ConfigDriver) *ConfigManager func (cm *ConfigManager) GetAPIConfig(apiPath string) (*APIConfig, error) func (cm *ConfigManager) GetVersionMapping(apiPath string, version int) (*VersionMapping, error) ``` ### 3. Recorder（流量录制器） 录制和回放 API 流量。 ```go func NewRecorder(config *RecorderConfig) *Recorder func (r *Recorder) Record(record *RecordedResponse) error func (r *Recorder) Replay(req *ReplayRequest) (*ReplayResult, error) ``` ### 4. SchemaProbe（结构探测） 自动提取 API 响应结构并生成映射建议。 ```go func NewSchemaProbe(config *ProbeConfig) *SchemaProbe func (sp *SchemaProbe) ExtractSchema(body []byte) (*FieldSchema, error) func (sp *SchemaProbe) Diff(oldSchema, newSchema *FieldSchema) *DiffReport func (sp *SchemaProbe) GenerateMapping(report *DiffReport) ([]FieldMapping, error) ``` ## 存储驱动配置 ### GoMemory（内存存储） ```go driver := driver.NewGoMemoryDriver() ``` ### MySQL ```go driver, err := driver.NewMySQLDriver(&driver.MySQLConfig{ Host: "localhost", Port: 3306, Database: "resilience", Username: "root", Password: "password", }) ``` ### Redis ```go driver, err := driver.NewRedisDriver(&driver.RedisConfig{ Addr: "localhost:6379", Password: "", DB: 0, }) ``` ## 代码风格指南 1. **包命名** - 小写单词，不使用下划线 2. **导出函数** - 大写字母开头，添加注释 3. **错误处理** - 使用 `model.NewError()` 创建标准化错误 4. **接口定义** - 在 `driver/interface.go` 集中定义 5. **类型别名** - 在 `core/exports.go` 中统一导出 ## 注意事项 1. Go 版本要求：1.22+ 2. Beego 集成需要 Go 1.24+，当前使用通用 HTTP Handler 方式 3. 生产环境建议使用 MySQL 或 Redis 驱动 4. 流量录制需要配置存储后端（S3/OSS/COS/MinIO）