# 分表查询服务使用指南 ## 概述 `ShardingQueryService` 是一个通用的分表查询服务，用于简化多分表查询的实现。它封装了 UNION ALL 查询、分页、排序等通用逻辑，让开发者只需要关注业务特定的筛选条件和列定义。 ## 核心优势 1. **代码复用**：避免为每个分表重复编写 UNION ALL 查询逻辑 2. **统一优化**：所有分表查询都使用相同的优化策略（表存在性检查、列名明确指定等） 3. **易于维护**：通用逻辑集中管理，修改一处即可影响所有使用该服务的表 4. **类型安全**：通过接口和回调函数保证类型安全 ## 使用步骤 ### 1. 定义筛选条件结构体 ```go // 例如：日志表的筛选条件 type LogFilters struct { UserID uint // 用户ID Level string // 日志级别 Keyword string // 关键词搜索 StartTime time.Time // 开始时间 EndTime time.Time // 结束时间 OrderBy string // 排序字段（格式：字段:asc/desc） } ``` ### 2. 实现 WHERE 条件构建函数 ```go // buildLogWhereClause 构建日志查询的 WHERE 条件 func (s *LogServiceImpl) buildLogWhereClause(filters any) (string, []any) { logFilters, ok := filters.(LogFilters) if !ok { return "", nil } var conditions []string var args []any // 时间范围 if !logFilters.StartTime.IsZero() { conditions = append(conditions, "created_at >= ?") args = append(args, logFilters.StartTime) } if !logFilters.EndTime.IsZero() { conditions = append(conditions, "created_at <= ?") args = append(args, logFilters.EndTime) } // 用户ID筛选 if logFilters.UserID > 0 { conditions = append(conditions, "user_id = ?") args = append(args, logFilters.UserID) } // 日志级别筛选 if logFilters.Level != "" { conditions = append(conditions, "level = ?") args = append(args, logFilters.Level) } // 关键词搜索 if logFilters.Keyword != "" { conditions = append(conditions, "(message LIKE ? OR context LIKE ?)") keyword := "%" + logFilters.Keyword + "%" args = append(args, keyword, keyword) } return strings.Join(conditions, " AND "), args } ``` ### 3. 实现列名获取函数 ```go // getLogTableColumns 获取日志表的所有列名 func (s *LogServiceImpl) getLogTableColumns() string { // 只包含模型中定义的字段，确保所有分表都有这些字段 columns := []string{ "id", "user_id", "level", "message", "context", "created_at", "updated_at", "deleted_at", } return strings.Join(columns, ", ") } ``` ### 4. 初始化分表查询服务 ```go type LogServiceImpl struct { shardingService ShardingService shardingQueryService ShardingQueryService } func NewLogService() *LogServiceImpl { service := &LogServiceImpl{ shardingService: NewShardingService(), } // 初始化分表查询服务 service.shardingQueryService = NewShardingQueryService(ShardingQueryConfig{ BaseTableName: "logs", GetColumns: func() string { return service.getLogTableColumns() }, BuildWhereClause: func(filters any) (string, []any) { return service.buildLogWhereClause(filters) }, GetAllowedOrderFields: func() map[string]bool { return map[string]bool{ "id": true, "user_id": true, "level": true, "created_at": true, "updated_at": true, } }, DefaultOrderBy: "created_at:desc", ModuleName: "log", }) return service } ``` ### 5. 使用分表查询服务 ```go // GetLogs 查询日志列表（支持多分表） func (s *LogServiceImpl) GetLogs(filters LogFilters, page, pageSize int) ([]models.Log, int64, error) { // 验证时间范围 valid, err := utils.ValidateTimeRange(filters.StartTime, filters.EndTime) if !valid { return nil, 0, err } // 获取需要查询的所有分表 tableNames := utils.GetShardingTableNames("logs", filters.StartTime, filters.EndTime) if len(tableNames) == 0 { return []models.Log{}, 0, nil } // 如果只有一个分表，直接查询（使用 ORM） if len(tableNames) == 1 { return s.querySingleTable(tableNames[0], filters, page, pageSize) } // 多个分表：使用通用分表查询服务 var logs []models.Log total, err := s.shardingQueryService.QueryMultipleTables(tableNames, filters, page, pageSize, &logs) if err != nil { return nil, 0, err } return logs, total, nil } // GetAllLogsForExport 获取所有日志用于导出 func (s *LogServiceImpl) GetAllLogsForExport(filters LogFilters) ([]models.Log, error) { // 验证时间范围 valid, err := utils.ValidateTimeRange(filters.StartTime, filters.EndTime) if !valid { return nil, err } // 获取需要查询的所有分表 tableNames := utils.GetShardingTableNames("logs", filters.StartTime, filters.EndTime) if len(tableNames) == 0 { return []models.Log{}, nil } // 如果只有一个分表，直接查询 if len(tableNames) == 1 { query := s.buildShardingQuery(tableNames[0], filters) orderBy := filters.OrderBy if orderBy == "" { orderBy = "created_at:desc" } query = s.applyOrderBy(query, orderBy) var logs []models.Log if err := query.Find(&logs); err != nil { return nil, apperrors.ErrQueryFailed.WithError(err) } return logs, nil } // 多个分表：使用通用分表查询服务 var logs []models.Log err = s.shardingQueryService.QueryMultipleTablesForExport(tableNames, filters, &logs) if err != nil { return nil, err } return logs, nil } ``` ## 配置说明 ### ShardingQueryConfig 字段说明 | 字段 | 类型 | 说明 | 必填 | |------|------|------|------| | `BaseTableName` | `string` | 基础表名，如 "orders" | 是 | | `GetColumns` | `func() string` | 获取表的所有列名（用于 UNION ALL 查询） | 是 | | `BuildWhereClause` | `func(any) (string, []any)` | 构建 WHERE 条件，返回条件字符串和参数列表 | 是 | | `GetAllowedOrderFields` | `func() map[string]bool` | 获取允许排序的字段列表 | 是 | | `DefaultOrderBy` | `string` | 默认排序，格式：字段:方向，如 "created_at:desc" | 否（默认：created_at:desc） | | `ModuleName` | `string` | 模块名称，用于日志记录 | 否（默认：sharding） | ## 注意事项 1. **列名必须明确指定**：不要使用 `SELECT *`，必须明确列出所有列名，确保不同分表的列数一致 2. **只包含模型中的字段**：列名列表应该只包含模型中定义的字段，避免查询不存在的字段 3. **WHERE 条件格式**：`BuildWhereClause` 返回的条件字符串不应该包含 `WHERE` 关键字，只返回条件部分（如 "user_id = ? AND status = ?"） 4. **时间范围处理**：如果筛选条件包含时间范围，应该在调用 `QueryMultipleTables` 之前验证时间范围 5. **单表优化**：如果只有一个分表，建议直接使用 ORM 查询，而不是使用 UNION ALL（性能更好） ## 完整示例 参考 `app/services/order_service.go` 中的实现，这是使用通用分表查询服务的完整示例。 ## 优势对比 ### 使用通用服务前（每个表都需要重复实现） ```go // 每个表都需要实现这些方法 func (s *OrderServiceImpl) queryMultipleTablesWithUnion(...) { /* 100+ 行代码 */ } func (s *LogServiceImpl) queryMultipleTablesWithUnion(...) { /* 100+ 行代码 */ } func (s *PaymentServiceImpl) queryMultipleTablesWithUnion(...) { /* 100+ 行代码 */ } // ... 每个表都重复 ``` ### 使用通用服务后（只需配置） ```go // 每个表只需要配置一次 service.shardingQueryService = NewShardingQueryService(ShardingQueryConfig{ // ... 配置 }) // 使用时只需一行代码 total, err := s.shardingQueryService.QueryMultipleTables(tableNames, filters, page, pageSize, &results) ``` ## 扩展性 如果需要添加新的通用功能（如缓存、性能监控等），只需要在 `ShardingQueryService` 中修改一次，所有使用该服务的表都会自动获得这些功能。