96ed936079
- 新增API端点参考文档，涵盖权限、卡密、订单、商户、监控、限制等模块 - 详细说明Apple卡密充值处理流程，包括提交、查询、回调和轮询接口 - 描述充值订单状态机及生命周期，支持超时重试和状态迁移 - 介绍签名验证、幂等控制及重复卡密防刷单策略 - 增加商户配置管理、历史记录查询和错误处理机制说明 - 提供API使用示例代码及客户端实现指导 - 删除过时的.drone.yml.bak文件，清理无用配置 - 添加.dockerignore忽略指定目录和文件
10 KiB
中间件与拦截器
**Referenced Files in This Document** - [auth.go](file://internal/middleware/auth.go) - [error_handler.go](file://internal/middleware/error_handler.go) - [user_token.go](file://utility/token/user_token.go) - [config.go](file://utility/config/config.go) - [code.go](file://internal/errHandler/code.go)目录
简介
本文档详细介绍了kami_backend项目中的中间件和拦截器系统，重点分析了认证中间件(auth.go)和错误处理中间件(error_handler.go)的实现。文档描述了这些中间件如何在请求处理流程中实现用户身份验证、授权检查以及统一的API响应格式化。通过深入分析中间件的实现细节、配置选项和使用模式，为开发者提供了创建自定义中间件的指南和最佳实践。
项目结构
kami_backend项目的中间件系统主要位于internal/middleware目录下，包含两个核心文件：auth.go和error_handler.go。这些中间件与utility目录下的工具模块（如token、config、verify）紧密协作，共同构成了系统的安全和错误处理基础设施。
graph TD
subgraph "中间件层"
A[auth.go]
B[error_handler.go]
end
subgraph "工具层"
C[token]
D[config]
E[verify]
F[cache]
end
A --> C
A --> D
A --> E
B --> F
C --> D
C --> F
Diagram sources
Section sources
核心组件
kami_backend的中间件系统由两个核心组件构成：认证中间件和错误处理中间件。认证中间件负责处理用户身份验证和授权检查，支持多种认证方式；错误处理中间件则负责统一处理和格式化API响应，确保系统返回一致的错误信息格式。
Section sources
架构概述
kami_backend的中间件系统采用分层架构设计，将认证逻辑与错误处理逻辑分离。认证中间件实现了灵活的认证策略，支持白名单、登录认证和iFrame认证三种模式。错误处理中间件则作为统一的错误捕获和响应层，确保所有API调用返回标准化的响应格式。
graph TB
Client[客户端] --> AuthMiddleware[认证中间件]
AuthMiddleware --> BusinessLogic[业务逻辑]
BusinessLogic --> ErrorHandler[错误处理中间件]
ErrorHandler --> Client
subgraph "认证策略"
WhiteList[白名单认证]
LoginAuth[登录认证]
IFrameAuth[iFrame认证]
end
AuthMiddleware --> WhiteList
AuthMiddleware --> LoginAuth
AuthMiddleware --> IFrameAuth
Diagram sources
详细组件分析
认证中间件分析
认证中间件是kami_backend安全体系的核心，实现了多模式的身份验证机制。该中间件通过LoginOrIframeAuth函数协调不同的认证策略，根据请求头中的tokenFrom字段选择适当的认证方式。
认证流程类图
classDiagram
class AuthMiddleware {
+LoginOrIframeAuth(r *ghttp.Request)
+whiteListAuth(r *ghttp.Request) gcode.Code
+loginAuth(r *ghttp.Request) gcode.Code
+iFrameAuth(r *ghttp.Request) gcode.Code
}
class TokenUtil {
+GetRequestToken(r *ghttp.Request) string
+ParseUserToken(ctx context.Context, tokenStr string) (*UserToken, error)
+RefreshUserToken(ctx context.Context, userToken UserToken) (string, error)
+GetTokenFromRedis(ctx context.Context, userID string, uuid string) (string, error)
}
class ConfigUtil {
+NewConfig(ctx context.Context) *Config
+GetTokenOptions() (TokenOptions, error)
+GetFrontendSecret() (SecretModel, error)
}
class CacheUtil {
+Set(ctx context.Context, key string, value interface{}, ttl time.Duration) error
+Get(ctx context.Context, key string) (*gvar.Var, error)
+Remove(ctx context.Context, key string) error
}
AuthMiddleware --> TokenUtil : "使用"
AuthMiddleware --> ConfigUtil : "使用"
TokenUtil --> CacheUtil : "使用"
TokenUtil --> ConfigUtil : "使用"
Diagram sources
认证流程序列图
sequenceDiagram
participant Client as "客户端"
participant AuthMiddleware as "认证中间件"
participant TokenUtil as "Token工具"
participant ConfigUtil as "配置工具"
participant Cache as "缓存系统"
Client->>AuthMiddleware : 发送API请求
AuthMiddleware->>AuthMiddleware : 检查白名单
alt 在白名单中
AuthMiddleware-->>Client : 直接放行
else 需要认证
AuthMiddleware->>AuthMiddleware : 检查tokenFrom头
alt tokenFrom=login
AuthMiddleware->>TokenUtil : GetRequestToken()
TokenUtil-->>AuthMiddleware : 返回Token
AuthMiddleware->>TokenUtil : ParseUserToken()
TokenUtil-->>AuthMiddleware : 返回用户Token信息
AuthMiddleware->>Cache : GetTokenFromRedis()
Cache-->>AuthMiddleware : 返回缓存的Token
AuthMiddleware->>TokenUtil : RefreshUserToken()
TokenUtil-->>AuthMiddleware : 返回新Token
AuthMiddleware->>Client : 设置refresh-token头
AuthMiddleware-->>Client : 放行请求
else tokenFrom=iframe
AuthMiddleware->>TokenUtil : GetRequestToken()
TokenUtil-->>AuthMiddleware : 返回Token
AuthMiddleware->>ConfigUtil : GetFrontendSecret()
ConfigUtil-->>AuthMiddleware : 返回密钥和IV
AuthMiddleware->>Verify : AesCBCURLDecryptWithBase64()
Verify-->>AuthMiddleware : 解密Token
AuthMiddleware->>AuthMiddleware : 验证Token时效性
AuthMiddleware-->>Client : 放行请求
else 未知来源
AuthMiddleware-->>Client : 返回"token来源不明"错误
end
end
Diagram sources
白名单认证流程
flowchart TD
Start([开始]) --> CheckPath["检查请求路径"]
CheckPath --> IsInWhiteList{"路径在白名单中?"}
IsInWhiteList --> |是| ReturnOK["返回CodeOK"]
IsInWhiteList --> |否| ReturnNotAuthorized["返回CodeNotAuthorized"]
ReturnOK --> End([结束])
ReturnNotAuthorized --> End
Diagram sources
错误处理中间件分析
错误处理中间件负责捕获和格式化API响应，确保系统返回一致的错误信息格式。该中间件在请求处理链的末端执行，能够捕获业务逻辑层抛出的任何错误，并将其转换为标准化的JSON响应。
错误处理流程
flowchart TD
Start([开始]) --> NextMiddleware["执行后续中间件"]
NextMiddleware --> GetError["获取错误信息"]
GetError --> GetResponse["获取响应数据"]
GetError --> GetCode["获取错误码"]
GetCode --> IsNil{"错误码为空?"}
IsNil --> |是| SetNilCode["设置为CodeNil"]
IsNil --> |否| UseErrorCode["使用实际错误码"]
SetNilCode --> CheckError["检查是否有错误"]
UseErrorCode --> CheckError
CheckError --> HasError{"存在错误?"}
HasError --> |是| IsCritical{"是CodeNil或CodeInternalPanic?"}
HasError --> |否| End([结束])
IsCritical --> |是| SetStatus200["设置状态码为200"]
IsCritical --> |否| End
SetStatus200 --> ClearBuffer["清空缓冲区"]
ClearBuffer --> WriteJson["写入JSON响应"]
WriteJson --> End
Diagram sources
依赖分析
kami_backend的中间件系统依赖于多个核心模块，形成了一个紧密耦合但职责分明的架构。认证中间件依赖于token、config和verify模块来实现完整的认证功能，而错误处理中间件则依赖于GoFrame框架的错误处理机制。
graph TD
AuthMiddleware[auth.go] --> Token[user_token.go]
AuthMiddleware --> Config[config.go]
AuthMiddleware --> Verify[verify.go]
Token --> Cache[cache.go]
Token --> Config
ErrorMiddleware[error_handler.go] --> GFError[gerror]
ErrorMiddleware --> GFCode[gcode]
ErrorMiddleware --> GFHttp[ghttp]
subgraph "utility"
Token
Config
Verify
Cache
end
subgraph "internal/middleware"
AuthMiddleware
ErrorMiddleware
end
Diagram sources
Section sources
性能考虑
中间件系统的性能主要受Token验证和缓存操作的影响。认证中间件通过Redis缓存Token信息，避免了重复的JWT解析和验证操作，提高了认证效率。同时，白名单机制避免了对公开API的不必要的认证检查，进一步优化了性能。
故障排除指南
当遇到中间件相关问题时，可以参考以下常见问题和解决方案：
- Token验证失败：检查
tokenFrom头是否正确设置，确认Token格式是否正确。 - 认证超时：检查配置中的Token超时设置，确认Redis缓存是否正常工作。
- 错误响应格式不一致：确保所有业务逻辑都使用标准的错误码系统。
- iFrame认证失败：检查前端密钥和IV配置是否正确，确认Token加密方式是否匹配。
Section sources
结论
kami_backend的中间件系统设计合理，实现了安全性和可维护性的平衡。认证中间件通过灵活的策略支持多种认证方式，而错误处理中间件则确保了API响应的一致性。建议在开发新功能时遵循现有的中间件模式，确保系统的整体一致性和安全性。