helper

func Chain ¶

func Chain(handlers ...context.Handler) context.Handler

Chain 组合多个 Handler 为一个 Handler

按顺序执行所有 Handler，如果任何一个返回错误，立即停止并返回该错误。

使用场景：

• 将复杂的业务逻辑分解为多个步骤
• 复用常见的 Handler 逻辑
• 保持代码清晰和可维护

示例：

validateInput := func(ctx *context.Context) error {
    // 验证输入
    return nil
}

processData := func(ctx *context.Context) error {
    // 处理数据
    return nil
}

formatOutput := func(ctx *context.Context) error {
    // 格式化输出
    return nil
}

handler := helper.Chain(
    validateInput,
    processData,
    formatOutput,
)

eng.OnCommand("/api").Handle(handler)

错误处理：

• 如果任何一个 Handler 返回错误，链立即停止
• 返回第一个遇到的错误

func ChainGeneric ¶

func ChainGeneric[Ctx any](handlers ...func(Ctx) error) func(Ctx) error

ChainGeneric 将多个具有相同签名的函数合并为一个函数。

函数按顺序执行，若任一函数返回错误，链式调用立即停止并返回该错误。

这是泛型版本，适用于任意上下文类型，而非仅限于 *context.Context。 若要对 Remilia 专属的 context.Handler 进行链式调用，请使用 handler.go 中的非泛型 Chain 函数。

示例：

// 用于自定义上下文类型
type MyContext struct { UserID string }
handler := ChainGeneric[*MyContext](
    validateInput,
    parseCommand,
    executeLogic,
)

// 用于 HTTP 上下文
type HTTPContext struct { /* ... */ }
httpHandler := ChainGeneric[*HTTPContext](
    authMiddleware,
    rateLimit,
    businessLogic,
)

性能：

• 空链或单处理器链零分配
• 多处理器链极低额外开销

func ChainWithNext ¶

func ChainWithNext[Ctx any](middlewares ...func(Ctx, func(Ctx) error) error) func(Ctx, func(Ctx) error) error

ChainWithNext 将中间件风格（接受"next"处理器）的函数组合在一起。

适用于构建中间件链，每个中间件可决定是否调用链中的下一个处理器。

并发安全性：返回的函数每次调用都会创建独立的执行状态，因此可并发调用。 但每条单独的调用链必须顺序执行（即单个中间件不得从多个 goroutine 并发调用 next()）。

示例：

middleware := ChainWithNext[*context.Context](
    func(ctx *context.Context, next func(*context.Context) error) error {
        // 前置处理
        if err := validateAuth(ctx); err != nil {
            return err
        }
        // 调用下一个处理器
        if err := next(ctx); err != nil {
            return err
        }
        // 后置处理
        logRequest(ctx)
        return nil
    },
    // ... 更多中间件
)

func Conditional ¶

func Conditional(condition context.Handler, thenHandler, elseHandler context.Handler) context.Handler

Conditional 根据条件选择执行不同的 Handler

先执行 condition Handler，如果成功则执行 thenHandler，否则执行 elseHandler。

使用场景：

• 根据上下文条件执行不同的逻辑
• 实现条件分支

示例：

isAdmin := func(ctx *context.Context) error {
    if !ctx.HasPermission("admin") {
        return errors.New("not admin")
    }
    return nil
}

adminHandler := func(ctx *context.Context) error {
    return ctx.Reply("Admin panel")
}

userHandler := func(ctx *context.Context) error {
    return ctx.Reply("User panel")
}

handler := helper.Conditional(isAdmin, adminHandler, userHandler)
eng.OnCommand("/panel").Handle(handler)

注意：

• elseHandler 可以为 nil，此时条件失败会直接返回 condition 的错误

func HideURL ¶

func HideURL(url string) string

HideURL 隐藏URL

url := "https://example.com/secret"
hidden := HideURL(url)
fmt.Println(hidden)

Output:
🔒example点com/secret

func Parallel ¶

func Parallel(handlers ...context.Handler) context.Handler

Parallel 并行执行多个 Handler

所有 Handler 在独立的 goroutine 中并行执行。 等待所有 Handler 完成后，如果有任何错误，返回所有错误的组合。

使用场景：

• 需要同时执行多个独立的操作
• 提高 I/O 密集型操作的性能
• 并行获取多个数据源

示例：

fetchUserData := func(ctx *context.Context) error {
    // 获取用户数据
    return nil
}

fetchProductData := func(ctx *context.Context) error {
    // 获取产品数据
    return nil
}

fetchOrderData := func(ctx *context.Context) error {
    // 获取订单数据
    return nil
}

handler := helper.Parallel(
    fetchUserData,
    fetchProductData,
    fetchOrderData,
)

eng.OnCommand("/dashboard").Handle(handler)

注意事项：

• Handler 必须是并发安全的
• 对 Context 的修改可能导致竞态条件
• 所有 Handler 都会执行，即使某些失败
• 如果多个 Handler 返回错误，所有错误会被组合返回

错误处理：

• 使用 errors.Join() 组合所有错误
• 只有在所有 Handler 完成后才返回

func Recover ¶

func Recover(h context.Handler) context.Handler

Recover 包装 Handler，捕获 panic 并转换为 error

使用场景：

• 保护关键的 Handler 不因 panic 而崩溃
• 提供优雅的错误处理

示例：

riskyHandler := func(ctx *context.Context) error {
    // 可能 panic 的代码
    return nil
}

safeHandler := helper.Recover(riskyHandler)
eng.OnCommand("/risky").Handle(safeHandler)

func StringPipe ¶

func StringPipe(funcs ...func(string) string) func(string) string

StringPipe 创建字符串转换管道。

这是为字符串预配置 Pipe 的便捷函数。

示例：

slugify := StringPipe(
    strings.TrimSpace,
    strings.ToLower,
    func(s string) string { return strings.ReplaceAll(s, " ", "-") },
)
slug := slugify("  Hello World  ")  // "hello-world"

func StringReplace ¶

func StringReplace(old, new string) func(string) string

StringReplace 创建一个将所有 old 替换为 new 的函数。

func ToMiddleware ¶

func ToMiddleware(h context.Handler) context.Middleware

ToMiddleware 将 Handler 转换为 Middleware

转换后的中间件会先执行该 Handler，如果成功则继续执行下一个 Handler。 如果 Handler 返回错误，不会调用 next Handler。

使用场景：

• 将 Handler 逻辑作为中间件使用
• 在 Handler 之前执行验证或预处理
• 复用现有的 Handler 逻辑

示例：

validateAuth := func(ctx *context.Context) error {
    if !isAuthenticated(ctx) {
        return errors.New("unauthorized")
    }
    return nil
}

eng.OnCommand("/api").
    Use(helper.ToMiddleware(validateAuth)).
    Use(helper.ToMiddleware(parseInput)).
    Handle(businessLogic)

注意：

• 如果 Handler 返回错误，中间件链会停止，不会调用后续中间件或 Handler
• 与直接使用中间件的区别在于，这允许复用现有的 Handler 函数