bdata/ADVANCED_QUERY_MIGRATION.md

ExtendPropertyValues 迁移到 AdvancedQuery 说明

变更时间

2026-05-21

变更原因

为了提供更强大、更易用的查询功能，将原有的 ExtendPropertyValues 参数替换为 AdvancedQuery 参数。底层服务会将 AdvancedQueryParams 解析为 ExtendPropertyValues。

---

变更内容

1. QueryActivitiesParams 变更

修改前

type QueryActivitiesParams struct {
    Name                 string           `json:"name,omitempty"`
    ActorID              string           `json:"actorId,omitempty"`
    BusinessType         []string         `json:"businessType,omitempty"`
    ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`  // 旧参数
    CreateUserID         string           `json:"createUserId,omitempty"`
    TenantID             string           `json:"tenantId"`
    PageNo               int              `json:"pageNo"`
    PageSize             int              `json:"pageSize"`
}

修改后

type QueryActivitiesParams struct {
    Name          string               `json:"name,omitempty"`
    ActorID       string               `json:"actorId,omitempty"`
    BusinessType  []string             `json:"businessType,omitempty"`
    AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`  // 新参数
    CreateUserID  string               `json:"createUserId,omitempty"`
    TenantID      string               `json:"tenantId"`
    PageNo        int                  `json:"pageNo"`
    PageSize      int                  `json:"pageSize"`
}

2. QueryPlansParams 变更

修改前

type QueryPlansParams struct {
    PlanType             string           `json:"planType,omitempty"`
    Name                 string           `json:"name,omitempty"`
    ActorID              string           `json:"actorId,omitempty"`
    State                string           `json:"state,omitempty"`
    BusinessType         []string         `json:"businessType,omitempty"`
    ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`  // 旧参数
    CreateUserID         string           `json:"createUserId,omitempty"`
    TenantID             string           `json:"tenantId"`
    PageNo               int              `json:"pageNo"`
    PageSize             int              `json:"pageSize"`
}

修改后

type QueryPlansParams struct {
    PlanType      string               `json:"planType,omitempty"`
    Name          string               `json:"name,omitempty"`
    ActorID       string               `json:"actorId,omitempty"`
    State         string               `json:"state,omitempty"`
    BusinessType  []string             `json:"businessType,omitempty"`
    AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`  // 新参数
    CreateUserID  string               `json:"createUserId,omitempty"`
    TenantID      string               `json:"tenantId"`
    PageNo        int                  `json:"pageNo"`
    PageSize      int                  `json:"pageSize"`
}

---

AdvancedQueryParams 结构

type AdvancedQueryParams struct {
    ConditionGroups []ConditionGroup `json:"conditionGroups"`
    GroupLogic      LogicOperator    `json:"groupLogic"`
}

type ConditionGroup struct {
    Conditions []ConditionItem `json:"conditions"`
    Logic      LogicOperator   `json:"logic"`
}

type ConditionItem struct {
    Condition       *ConditionGroup `json:"condition,omitempty"`
    SingleCondition *QueryCondition `json:"singleCondition,omitempty"`
}

type QueryCondition struct {
    Field    string        `json:"field"`
    Operator QueryOperator `json:"operator"`
    Value    any           `json:"value,omitempty"`
}

type QueryOperator string
type LogicOperator string

---

迁移指南

旧方式（ExtendPropertyValues）

// 旧的查询方式
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    ExtendPropertyValues: map[string][]any{
        "(extend_properties->>'priority')::numeric = ?": {1},
        "(extend_properties->>'progress')::numeric > ?": {50},
        "extend_properties->>'deptName' = ?": {"技术部"},
    },
    PageNo:   1,
    PageSize: 10,
}

缺点：

• 需要手动编写 SQL 片段
• 容易出错（SQL 语法、类型转换）
• 不够直观
• 难以构建复杂的逻辑组合

新方式（AdvancedQuery）

// 新的查询方式
params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 50),
            managesdk.Equal("deptName", "技术部"),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}

优点：

• 类型安全
• 语义清晰
• 易于构建复杂查询
• 支持嵌套条件
• 自动处理类型转换

---

查询操作符对照表

旧方式（SQL）	新方式（AdvancedQuery）	说明
field = ?	Equal("field", value)	等于
field != ?	NotEqual("field", value)	不等于
field > ?	GreaterThan("field", value)	大于
field >= ?	GreaterEqual("field", value)	大于等于
field < ?	LessThan("field", value)	小于
field <= ?	LessEqual("field", value)	小于等于
field LIKE ?	Like("field", value)	模糊查询
field NOT LIKE ?	NotLike("field", value)	不包含
field LIKE 'prefix%'	StartsWith("field", "prefix")	以...开头
field LIKE '%suffix'	EndsWith("field", "suffix")	以...结尾
field IS NULL	IsNull("field")	为空
field IS NOT NULL	IsNotNull("field")	不为空
field IN (?, ?)	In("field", []any{v1, v2})	IN 查询
field NOT IN (?, ?)	NotIn("field", []any{v1, v2})	NOT IN 查询

---

迁移示例

示例 1：简单等值查询

旧方式

ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'priority')::numeric = ?": {1},
}

新方式

AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
    ),
)

示例 2：多条件 AND 查询

旧方式

ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'priority')::numeric = ?": {1},
    "(extend_properties->>'progress')::numeric > ?": {50},
    "extend_properties->>'deptName' = ?": {"技术部"},
}

新方式

AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
        managesdk.Equal("deptName", "技术部"),
    ),
)

示例 3：范围查询

旧方式

ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'duration')::numeric BETWEEN ? AND ?": {2.0, 8.0},
}

新方式

AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.GreaterEqual("duration", 2.0),
        managesdk.LessEqual("duration", 8.0),
    ),
)

示例 4：IN 查询

旧方式

ExtendPropertyValues: map[string][]any{
    "(extend_properties->>'complex')::numeric IN (?, ?)": {2, 3},
}

新方式

AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.In("complex", []int{2, 3}),
    ),
)

示例 5：模糊查询

旧方式

ExtendPropertyValues: map[string][]any{
    "extend_properties->>'memberName' LIKE ?": {"%张%"},
}

新方式

AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Like("memberName", "%张%"),
    ),
)

示例 6：OR 查询

旧方式

// 旧方式不支持 OR 查询，需要多次调用

新方式

AdvancedQuery: managesdk.OrQuery(
    managesdk.OrGroup(
        managesdk.Equal("priority", 1),
        managesdk.Equal("priority", 2),
    ),
)

示例 7：复杂组合查询

旧方式

// 旧方式难以表达：(priority = 1 AND progress > 50) OR (priority = 2 AND progress > 80)

新方式

AdvancedQuery: managesdk.OrQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.GreaterThan("progress", 50),
    ),
    managesdk.AndGroup(
        managesdk.Equal("priority", 2),
        managesdk.GreaterThan("progress", 80),
    ),
)

---

新增功能

1. 嵌套条件组

// (priority = 1 AND (progress > 50 OR duration > 4))
AdvancedQuery: managesdk.AndQuery(
    managesdk.AndGroup(
        managesdk.Equal("priority", 1),
        managesdk.NewNestedConditionGroup(
            managesdk.OrGroup(
                managesdk.GreaterThan("progress", 50),
                managesdk.GreaterThan("duration", 4),
            ),
        ),
    ),
)

2. 便捷的辅助函数

// 快速构建 AND 查询
managesdk.AndQuery(groups...)

// 快速构建 OR 查询
managesdk.OrQuery(groups...)

// 快速构建 AND 条件组
managesdk.AndGroup(conditions...)

// 快速构建 OR 条件组
managesdk.OrGroup(conditions...)

3. 丰富的操作符

• 基础比较：Equal, NotEqual, GreaterThan, GreaterEqual, LessThan, LessEqual
• 字符串匹配：Like, NotLike, StartsWith, EndsWith
• 空值判断：IsNull, IsNotNull
• 集合操作：In, NotIn

---

向后兼容性

⚠️ 这是一个破坏性变更

• ExtendPropertyValues 参数已被移除
• 所有使用 ExtendPropertyValues 的代码需要迁移到 AdvancedQuery

---

迁移步骤

1. 更新 SDK 版本

确保使用最新版本的 bdata SDK。

2. 替换查询参数

将所有 ExtendPropertyValues 替换为 AdvancedQuery。

3. 重写查询逻辑

使用新的查询构建器 API 重写查询条件。

4. 测试验证

充分测试所有查询功能，确保结果正确。

---

常见问题

Q1: 如何表达复杂的 SQL 条件？

A: 使用嵌套条件组和多个条件组合：

// (A AND B) OR (C AND D)
managesdk.OrQuery(
    managesdk.AndGroup(A, B),
    managesdk.AndGroup(C, D),
)

Q2: 如何进行 BETWEEN 查询？

A: 使用 GreaterEqual 和 LessEqual 组合：

managesdk.AndGroup(
    managesdk.GreaterEqual("field", min),
    managesdk.LessEqual("field", max),
)

Q3: 如何进行 NOT IN 查询？

A: 使用 NotIn 操作符：

managesdk.NotIn("field", []any{v1, v2, v3})

Q4: 字段名需要加前缀吗？

A: 不需要，直接使用字段名即可，底层服务会自动处理：

// 正确
managesdk.Equal("priority", 1)

// 错误（不需要加前缀）
managesdk.Equal("extend_properties->>'priority'", 1)

Q5: 数值类型需要转换吗？

A: 不需要，底层服务会自动处理类型转换：

// 正确
managesdk.Equal("priority", 1)

// 不需要手动转换
managesdk.Equal("(extend_properties->>'priority')::numeric", 1)

---

相关文档

• ACTIVITY_PLAN_USAGE.md - 完整的使用文档
• advanced_query.go - AdvancedQuery 实现源码
• model.go - 数据模型定义

---

总结

优势

✅ 类型安全：编译时检查，减少运行时错误
✅ 易于使用：语义清晰，无需编写 SQL
✅ 功能强大：支持复杂的逻辑组合和嵌套
✅ 可维护性：代码更清晰，易于理解和修改
✅ 扩展性：易于添加新的操作符和功能

迁移建议

1. 优先迁移简单查询
2. 逐步迁移复杂查询
3. 充分测试每个迁移点
4. 保留旧代码作为参考

---

变更完成时间：2026-05-21
变更人员：Kiro AI
状态：✅ 已完成