搜索标签

VEF Framework 支持通过 struct tag 定义搜索条件，自动将搜索参数转换为数据库查询。

基本用法

定义搜索参数

type UserSearch struct {
    Username     string `search:"like"`           // LIKE '%value%'
    Email        string `search:"eq"`             // = value
    IsActive     *bool  `search:"eq"`             // = value (pointer for optional)
    DepartmentId string `search:"eq"`             // = value
    CreatedAt    string `search:"gte" column:"created_at"` // >= value
}

使用搜索参数

// In API definition
apis.NewFindPageApi[models.User, UserSearch]()

// Request
{
    "resource": "smp/sys/user",
    "action": "find_page",
    "params": {
        "username": "john",
        "isActive": true
    }
}

// Generated SQL
// SELECT * FROM users WHERE username LIKE '%john%' AND is_active = true

支持的操作符

操作符	说明	SQL
eq	等于	= value
ne	不等于	<> value
gt	大于	> value
gte	大于等于	>= value
lt	小于	< value
lte	小于等于	<= value
like	模糊匹配	LIKE '%value%'
likeLeft	左模糊	LIKE '%value'
likeRight	右模糊	LIKE 'value%'
in	包含	IN (values)
notIn	不包含	NOT IN (values)
between	范围	BETWEEN v1 AND v2
isNull	为空	IS NULL
isNotNull	不为空	IS NOT NULL

高级用法

指定列名

type UserSearch struct {
    // Field name differs from column name
    Name string `search:"like" column:"username"`
}

多字段搜索

type UserSearch struct {
    // Search in multiple columns
    Keyword string `search:"like" columns:"username,email,phone"`
}

日期范围搜索

type OrderSearch struct {
    StartDate string `search:"gte" column:"created_at"`
    EndDate   string `search:"lte" column:"created_at"`
}

可选字段

type UserSearch struct {
    // Use pointer for optional fields
    IsActive *bool   `search:"eq"`
    Role     *string `search:"eq"`
}

自定义搜索逻辑

忽略空值

type UserSearch struct {
    Username string `search:"like" ignoreEmpty:"true"`
    Email    string `search:"eq" ignoreEmpty:"true"`
}

自定义条件

type UserSearch struct {
    Keyword string `search:"-"` // Ignore in auto search
}

// Handle manually in API
apis.NewFindPageApi[models.User, UserSearch]().
    WithDynamicCondition(func(ctx fiber.Ctx, search UserSearch) func(q *orm.Query[models.User]) *orm.Query[models.User] {
        return func(q *orm.Query[models.User]) *orm.Query[models.User] {
            if search.Keyword != "" {
                q = q.WhereGroup(func(q *orm.Query[models.User]) *orm.Query[models.User] {
                    return q.
                        WhereLike("username", "%"+search.Keyword+"%").
                        OrWhereLike("email", "%"+search.Keyword+"%").
                        OrWhereLike("phone", "%"+search.Keyword+"%")
                })
            }
            return q
        }
    })

关联表搜索

搜索关联字段

type UserSearch struct {
    DepartmentName string `search:"like" column:"Department.name" join:"Department"`
}

嵌套关联搜索

type UserSearch struct {
    CompanyName string `search:"like" column:"Department.Company.name" join:"Department.Company"`
}

完整示例

package payloads

// UserSearch defines search parameters for user queries
type UserSearch struct {
    // Basic fields
    Username     string  `search:"like"`
    Email        string  `search:"like"`
    Phone        string  `search:"like"`
    
    // Exact match
    DepartmentId string  `search:"eq"`
    Role         string  `search:"eq"`
    
    // Boolean (use pointer for optional)
    IsActive     *bool   `search:"eq"`
    IsAdmin      *bool   `search:"eq"`
    
    // Range
    AgeMin       *int    `search:"gte" column:"age"`
    AgeMax       *int    `search:"lte" column:"age"`
    
    // Date range
    CreatedFrom  string  `search:"gte" column:"created_at"`
    CreatedTo    string  `search:"lte" column:"created_at"`
    
    // IN condition
    Ids          []string `search:"in" column:"id"`
    Statuses     []string `search:"in" column:"status"`
    
    // Custom keyword search (handled manually)
    Keyword      string  `search:"-"`
    
    // Pagination (not search conditions)
    Page         int     `search:"-"`
    PageSize     int     `search:"-"`
    
    // Sorting (not search conditions)
    SortField    string  `search:"-"`
    SortOrder    string  `search:"-"`
}

搜索标签参考

标签	说明	示例
search:"eq"	等于	WHERE column = value
search:"ne"	不等于	WHERE column <> value
search:"gt"	大于	WHERE column > value
search:"gte"	大于等于	WHERE column >= value
search:"lt"	小于	WHERE column < value
search:"lte"	小于等于	WHERE column <= value
search:"like"	模糊匹配	WHERE column LIKE '%value%'
search:"likeLeft"	左模糊	WHERE column LIKE '%value'
search:"likeRight"	右模糊	WHERE column LIKE 'value%'
search:"in"	包含	WHERE column IN (values)
search:"notIn"	不包含	WHERE column NOT IN (values)
search:"between"	范围	WHERE column BETWEEN v1 AND v2
search:"isNull"	为空	WHERE column IS NULL
search:"isNotNull"	不为空	WHERE column IS NOT NULL
search:"-"	忽略	不生成条件

附加标签	说明
column:"name"	指定数据库列名
columns:"a,b,c"	多列搜索（OR）
ignoreEmpty:"true"	忽略空值
join:"Relation"	关联表搜索

下一步

• 了解 条件构建器 手动构建复杂条件
• 学习 查询构建器 完整查询功能
• 查看 事务处理 确保数据一致性