Files

danial 2253dc739a feat(jd-cookie):优化订单创建逻辑与状态管理- 新增订单状态 OrderStatusJDOrderFailed用于标识京东订单获取失败

- 新增订单变更类型 OrderChangeTypeJDOrderFailed 用于记录下单失败事件
- 调整订单创建逻辑，支持失败订单重试机制
- 新增 RecordOrderHistoryReq 结构体统一记录订单变更历史参数
- 修改数据库表结构，优化字段类型和索引
- 更新订单创建逻辑，分离本地订单与京东订单创建流程- 增加失败订单重新创建京东订单的处理逻辑
- 调整订单状态检查逻辑，支持更多状态处理
-优化订单历史记录方式，增加备注信息支持
- 更新数据库字符集为 utf8mb4_unicode_ci 提升兼容性

2025-10-18 23:41:31 +08:00

14 KiB

Raw Blame History

中间件与拦截器

**本文档引用的文件** - [auth.go](file://internal/middleware/auth.go) - *在最近的提交中更新* - [error_handler.go](file://internal/middleware/error_handler.go) - *在最近的提交中更新* - [sys_auth.go](file://internal/service/sys_auth.go) - *定义认证服务接口* - [sysAuth.go](file://internal/logic/sys_auth/sysAuth.go) - *实现认证服务逻辑* - [jd_cookie_v1_create_account.go](file://internal/controller/jd_cookie/jd_cookie_v1_create_account.go) - *账户创建控制器* - [jd_cookie_v1_create_order.go](file://internal/controller/jd_cookie/jd_cookie_v1_create_order.go) - *订单创建控制器* - [jd_cookie_v1_batch_check.go](file://internal/controller/jd_cookie/jd_cookie_v1_batch_check.go) - *批量检测控制器* - [user_token.go](file://utility/token/user_token.go) - *在认证流程中使用* - [config.go](file://utility/config/config.go) - *在认证流程中使用* - [code.go](file://internal/errHandler/code.go) - *定义错误码*

更新摘要

已做更改

更新了认证中间件文档，反映LoginOnlyIFrame和LoginOnlyLogin认证策略的使用
添加了对SysAuth服务接口的详细说明
更新了JD Cookie模块的权限校验说明，包括账户创建和批量检测接口使用LoginOnlyIFrame
修正了订单创建接口不再需要权限校验的文档说明
更新了相关架构图和序列图以反映最新的认证流程
维护了源代码引用跟踪系统

简介

本文档详细介绍了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

图表来源

本节来源

核心组件

kami_backend的中间件系统由两个核心组件构成：认证中间件和错误处理中间件。认证中间件负责处理用户身份验证和授权检查，支持多种认证方式；错误处理中间件则负责统一处理和格式化API响应，确保系统返回一致的错误信息格式。

本节来源

架构概述

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

图表来源

详细组件分析

认证中间件分析

认证中间件是kami_backend安全体系的核心，实现了多模式的身份验证机制。该中间件通过LoginOrIframeAuth函数协调不同的认证策略，根据请求头中的tokenFrom字段选择适当的认证方式。

认证服务接口

系统通过SysAuth接口提供统一的认证服务，该接口定义了多种认证策略：

type ISysAuth interface {
    // LoginWithIFrameAndLogin Iframe和账号可以同时登陆
    LoginWithIFrameAndLogin(ctx context.Context) (userInfo *entity.V1SysUser, err error)
    LoginWithEverything(ctx context.Context) (output *model.SysAuthLoginWithEverythingOutput, err error)
    // LoginOnlyIFrame 只能IFrame登录
    LoginOnlyIFrame(ctx context.Context) (userInfo *entity.V1SysUser, err error)
    // LoginOnlyLogin 只能登录
    LoginOnlyLogin(ctx context.Context) (userInfo *entity.V1SysUser, err error)
}

本节来源

sys_auth.go

认证流程类图

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 : "使用"

图表来源

认证流程序列图

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

图表来源

白名单认证流程

flowchart TD
Start([开始]) --> CheckPath["检查请求路径"]
CheckPath --> IsInWhiteList{"路径在白名单中?"}
IsInWhiteList --> |是| ReturnOK["返回CodeOK"]
IsInWhiteList --> |否| ReturnNotAuthorized["返回CodeNotAuthorized"]
ReturnOK --> End([结束])
ReturnNotAuthorized --> End

图表来源

auth.go

错误处理中间件分析

错误处理中间件负责捕获和格式化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

图表来源

error_handler.go

JD Cookie模块权限校验更新

根据最新的代码变更，JD Cookie模块的权限校验策略已进行调整，具体如下：

账户创建权限校验

账户创建接口现在需要进行iFrame登录权限校验：

// CreateAccount 创建Cookie账户
func (c *ControllerV1) CreateAccount(ctx context.Context, req *v1.CreateAccountReq) (res *v1.CreateAccountRes, err error) {
    _, err = service.SysAuth().LoginOnlyIFrame(ctx)
    if err != nil {
        err = errHandler.WrapError(ctx, gcode.CodeNotAuthorized, err, "权限不足")
        return
    }
    // ... 业务逻辑
}

本节来源

jd_cookie_v1_create_account.go

批量检测权限校验

批量检测接口同样需要iFrame登录权限校验：

// BatchCheck 批量检测Cookie状态
func (c *ControllerV1) BatchCheck(ctx context.Context, req *v1.BatchCheckReq) (res *v1.BatchCheckRes, err error) {
    _, err = service.SysAuth().LoginOnlyIFrame(ctx)
    if err != nil {
        err = errHandler.WrapError(ctx, gcode.CodeNotAuthorized, err, "权限不足")
        return
    }
    // ... 业务逻辑
}

本节来源

jd_cookie_v1_batch_check.go

订单创建权限校验移除

订单创建接口不再需要权限校验，已从白名单中移除：

// CreateOrder 创建订单
func (c *ControllerV1) CreateOrder(ctx context.Context, req *v1.CreateOrderReq) (res *v1.CreateOrderRes, err error) {
    // 无需权限校验
    createOrderReq := &model.CreateOrderReq{
        UserOrderId: req.UserOrderId,
        Amount:      req.Amount,
        Category:    req.Category,
    }
    // ... 业务逻辑
}

本节来源

jd_cookie_v1_create_order.go

依赖分析

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

图表来源

本节来源

性能考虑

中间件系统的性能主要受Token验证和缓存操作的影响。认证中间件通过Redis缓存Token信息，避免了重复的JWT解析和验证操作，提高了认证效率。同时，白名单机制避免了对公开API的不必要的认证检查，进一步优化了性能。

故障排除指南

当遇到中间件相关问题时，可以参考以下常见问题和解决方案：

Token验证失败：检查tokenFrom头是否正确设置，确认Token格式是否正确。
认证超时：检查配置中的Token超时设置，确认Redis缓存是否正常工作。
错误响应格式不一致：确保所有业务逻辑都使用标准的错误码系统。
iFrame认证失败：检查前端密钥和IV配置是否正确，确认Token加密方式是否匹配。
权限不足错误：确认接口是否需要LoginOnlyIFrame或LoginOnlyLogin认证，检查认证头是否正确传递。

本节来源

结论

kami_backend的中间件系统设计合理，实现了安全性和可维护性的平衡。认证中间件通过灵活的策略支持多种认证方式，而错误处理中间件则确保了API响应的一致性。建议在开发新功能时遵循现有的中间件模式，确保系统的整体一致性和安全性。

14 KiB Raw Blame History Unescape Escape

中间件与拦截器

更新摘要

目录

简介

项目结构

核心组件

架构概述

详细组件分析

认证中间件分析

认证服务接口

认证流程类图

认证流程序列图

白名单认证流程

错误处理中间件分析

错误处理流程

JD Cookie模块权限校验更新

账户创建权限校验

批量检测权限校验

订单创建权限校验移除

依赖分析

性能考虑

故障排除指南

结论

14 KiB

Raw Blame History