bdata SDK API 变更总结

📋 变更概述

变更时间：2026-05-21
变更类型：破坏性变更
影响范围：Activity 和 Plan 查询接口

🔧 核心变更

参数替换

将 ExtendPropertyValues 参数替换为 AdvancedQuery 参数。

QueryActivitiesParams

// 旧参数（已移除）
ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`

// 新参数
AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`

QueryPlansParams

// 旧参数（已移除）
ExtendPropertyValues map[string][]any `json:"extendPropertyValues,omitempty"`

// 新参数
AdvancedQuery *AdvancedQueryParams `json:"advancedQuery,omitempty"`

📊 对比示例

旧方式（ExtendPropertyValues）

params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    ExtendPropertyValues: map[string][]any{
        "(extend_properties->>'priority')::numeric = ?": {1},
        "(extend_properties->>'progress')::numeric > ?": {50},
    },
    PageNo:   1,
    PageSize: 10,
}

缺点：

❌ 需要手动编写 SQL 片段
❌ 容易出错（SQL 语法、类型转换）
❌ 不支持复杂的 OR 逻辑
❌ 代码可读性差

新方式（AdvancedQuery）

params := managesdk.QueryActivitiesParams{
    TenantID: "tenant-001",
    AdvancedQuery: managesdk.AndQuery(
        managesdk.AndGroup(
            managesdk.Equal("priority", 1),
            managesdk.GreaterThan("progress", 50),
        ),
    ),
    PageNo:   1,
    PageSize: 10,
}

优点：

✅ 类型安全
✅ 语义清晰
✅ 支持复杂逻辑组合
✅ 代码可读性强
✅ 易于维护

🎯 支持的操作符

操作符	函数	示例
=	`Equal(field, value)`	`Equal("priority", 1)`
!=	`NotEqual(field, value)`	`NotEqual("status", "closed")`
>	`GreaterThan(field, value)`	`GreaterThan("progress", 50)`
>=	`GreaterEqual(field, value)`	`GreaterEqual("duration", 2.0)`
<	`LessThan(field, value)`	`LessThan("progress", 100)`
<=	`LessEqual(field, value)`	`LessEqual("duration", 8.0)`
LIKE	`Like(field, value)`	`Like("name", "%项目%")`
NOT LIKE	`NotLike(field, value)`	`NotLike("name", "%测试%")`
STARTS WITH	`StartsWith(field, value)`	`StartsWith("name", "项目")`
ENDS WITH	`EndsWith(field, value)`	`EndsWith("name", "完成")`
IS NULL	`IsNull(field)`	`IsNull("remark")`
IS NOT NULL	`IsNotNull(field)`	`IsNotNull("remark")`
IN	`In(field, values)`	`In("priority", []int{1, 2})`
NOT IN	`NotIn(field, values)`	`NotIn("status", []string{"closed"})`

💡 常用查询模式

1. 简单查询

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

2. 多条件 AND

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

3. 多条件 OR

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

4. 范围查询

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

5. IN 查询

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

6. 模糊查询

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

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),
    ),
)

📝 迁移清单

修改的文件

✅ bdata/model.go - 更新 QueryActivitiesParams 和 QueryPlansParams
✅ bdata/ACTIVITY_PLAN_USAGE.md - 更新使用文档
✅ bdata/ADVANCED_QUERY_MIGRATION.md - 创建迁移指南
✅ bdata/API_CHANGE_SUMMARY.md - 创建变更总结

需要迁移的代码

所有使用以下参数的代码需要迁移：

QueryActivitiesParams.ExtendPropertyValues
QueryPlansParams.ExtendPropertyValues

⚠️ 注意事项

1. 破坏性变更

这是一个破坏性变更，所有使用 ExtendPropertyValues 的代码必须迁移。

2. 字段名不需要前缀

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

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

3. 自动类型转换

底层服务会自动处理类型转换，无需手动转换：

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

// ❌ 不需要（底层自动处理）
managesdk.Equal("(extend_properties->>'priority')::numeric", 1)

4. 底层处理

底层服务会将 AdvancedQueryParams 解析为 ExtendPropertyValues，开发者无需关心实现细节。

📚 相关文档

ADVANCED_QUERY_MIGRATION.md - 详细的迁移指南
ACTIVITY_PLAN_USAGE.md - 完整的使用文档
advanced_query.go - AdvancedQuery 实现源码

✅ 优势总结

特性	旧方式	新方式
类型安全	❌	✅
易于使用	❌	✅
支持 OR 逻辑	❌	✅
支持嵌套条件	❌	✅
代码可读性	⭐⭐	⭐⭐⭐⭐⭐
可维护性	⭐⭐	⭐⭐⭐⭐⭐
扩展性	⭐⭐	⭐⭐⭐⭐⭐

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

API_CHANGE_SUMMARY.md 5.9 KB История Исходник