basesql

package module
v0.0.0-...-7d88a1d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2025 License: MIT Imports: 23 Imported by: 0

README

BaseSQL - 飞书多维表格 GORM Driver

BaseSQL 是一个将飞书多维表格（Base）封装为关系型数据库接口的 Go 组件，让您可以使用熟悉的 SQL 语法和 GORM ORM 来操作多维表格数据。

特性

  • 🚀 SQL 语法支持: 使用标准 SQL 语法操作多维表格
  • 🔧 GORM 兼容: 完全兼容 GORM ORM 框架
  • 🖥️ CLI 工具: 提供命令行工具，支持交互式 SQL 操作
  • 🔐 多种认证: 支持应用认证和用户认证
  • 📊 类型转换: 自动处理 Go 类型与飞书字段类型的转换
  • 🛠️ 自动迁移: 支持数据表结构的自动创建和更新
  • 🔄 CRUD 操作: 支持完整的增删改查操作
  • 📈 查询优化: 支持条件查询、排序、分页等高级功能
  • 🛡️ 稳定性保障: 内置熔断器、连接池、限流器等稳定性组件
  • 🔄 智能重试: 支持指数退避的自动重试机制
  • 📊 监控统计: 提供详细的性能和稳定性统计信息

安装

go get github.com/ag9920/basesql

快速开始

使用 CLI 工具（推荐）

BaseSQL 提供了一个强大的命令行工具，让你可以直接使用 SQL 语法操作飞书多维表格：

# 1. 构建 CLI 工具
make build

# 2. 快速体验（使用你的飞书应用凭据）
./bin/basesql query "SHOW TABLES" --app-id=your_app_id --app-secret=your_app_secret --app-token=your_app_token
./bin/basesql query "SELECT * FROM users" --app-id=your_app_id --app-secret=your_app_secret --app-token=your_app_token
./bin/basesql shell --app-id=your_app_id --app-secret=your_app_secret --app-token=your_app_token

# 3. 生产环境使用
# 初始化配置
./bin/basesql config init

# 编辑配置文件 ~/.basesql/config.env
# 填入你的飞书应用信息

# 测试连接
./bin/basesql connect

# 执行 SQL 查询
./bin/basesql query "SELECT * FROM users"

# 执行 SQL 操作
./bin/basesql exec "INSERT INTO users (name, email) VALUES ('张三', 'zhangsan@example.com')"

# 启动交互式 SQL shell
./bin/basesql shell

详细的 CLI 使用说明请参考 CLI.md。

1. 配置飞书应用

首先需要在飞书开放平台创建应用并获取相关凭证：

  1. 访问 飞书开放平台
  2. 创建企业自建应用
  3. 获取 App ID 和 App Secret
  4. 创建多维表格并获取 App Token
  5. 配置应用权限，确保有多维表格的读写权限
2. 基本使用
package main

import (
    "log"
    "time"
    
    basesql "github.com/ag9920/basesql"
    "gorm.io/gorm"
)

// 定义数据模型
type User struct {
    ID        string    `gorm:"primarykey"`
    Name      string    `gorm:"size:100"`
    Email     string    `gorm:"size:100"`
    Age       int
    Active    bool      `gorm:"default:true"`
    CreatedAt time.Time `gorm:"autoCreateTime"`
    UpdatedAt time.Time `gorm:"autoUpdateTime"`
}

func main() {
    // 配置连接
    config := &basesql.Config{
        AppID:     "your_app_id",     // 替换为你的 App ID
        AppSecret: "your_app_secret", // 替换为你的 App Secret
        AppToken:  "your_app_token",  // 替换为你的多维表格 App Token
        AuthType:  basesql.AuthTypeTenant,
        DebugMode: true,             // 开发时建议开启调试模式
    }

    // 连接数据库
    db, err := gorm.Open(basesql.Open(config), &gorm.Config{})
    if err != nil {
        log.Fatalf("failed to connect database: %v", err)
    }

    // 自动迁移
    if err := db.AutoMigrate(&User{}); err != nil {
        log.Fatalf("failed to migrate database: %v", err)
    }

    // 创建记录
    user := &User{
        Name:  "张三",
        Email: "zhangsan@example.com",
        Age:   25,
    }
    
    if err := db.Create(user).Error; err != nil {
        log.Fatalf("failed to create user: %v", err)
    }
    
    log.Printf("Created user: %+v", user)

    // 查询记录
    var users []User
    if err := db.Where("age > ?", 20).Find(&users).Error; err != nil {
        log.Fatalf("failed to query users: %v", err)
    }
    
    log.Printf("Found %d users", len(users))

    // 更新记录
    if err := db.Model(user).Update("age", 26).Error; err != nil {
        log.Fatalf("failed to update user: %v", err)
    }

    // 删除记录
    if err := db.Delete(user).Error; err != nil {
        log.Fatalf("failed to delete user: %v", err)
    }
}

认证配置

支持两种认证方式：

1. 应用认证 (推荐)
config := &basesql.Config{
    AppID:     "your_app_id",
    AppSecret: "your_app_secret",
    AppToken:  "your_app_token",
    AuthType:  basesql.AuthTypeTenant,
}
2. 用户认证
config := &basesql.Config{
    AppID:       "your_app_id",
    AppSecret:   "your_app_secret",
    AppToken:    "your_app_token",
    AuthType:    basesql.AuthTypeUser,
    AccessToken: "your_user_token", // 用户访问令牌
}
3. 环境变量配置 (推荐)

为了安全起见，建议使用环境变量来配置敏感信息。示例代码已经支持环境变量，你可以：

方式一：设置环境变量

export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret
export FEISHU_APP_TOKEN=your_app_token
export DEBUG_MODE=true

方式二：使用 .env 文件

# 复制示例文件
cp example/.env.example .env
# 编辑 .env 文件，填入你的配置

示例代码会自动优先使用环境变量，如果没有设置则使用代码中的默认值。

支持的数据类型

BaseSQL 支持飞书多维表格的核心字段类型，提供完整的类型转换和 SQL 操作支持：

飞书字段类型 Go 类型 说明 支持的 SQL 操作
单行文本 string 简短文本内容，单行显示 =, LIKE, IN, IS NULL, IS NOT NULL
多行文本 string 支持换行符的长文本内容 =, LIKE, IN, IS NULL, IS NOT NULL
数字 int, int64, float64 整数和浮点数值 =, >, <, >=, <=, IN, IS NULL, IS NOT NULL
复选框 bool 布尔值，支持 true/false =, IS NULL, IS NOT NULL
日期 time.Time, string 日期时间类型，支持多种格式 =, >, <, >=, <=, IS NULL, IS NOT NULL
链接 string URL 格式的链接地址 =, LIKE, IN, IS NULL, IS NOT NULL
多选 []string 多个选项组成的数组 IN, IS NULL, IS NOT NULL
单选 string 从预设选项中选择的单个值 =, IN, IS NULL, IS NOT NULL
人员 []string 人员信息，支持多人选择 IN, IS NULL, IS NOT NULL
类型转换说明
  • 自动转换：BaseSQL 自动处理 Go 类型与飞书字段类型之间的转换
  • 空值处理：所有字段类型都支持空值检查（IS NULL/IS NOT NULL）
  • 数组类型：多选和人员字段自动处理数组与字符串的转换
  • 日期格式：支持 RFC3339、ISO8601 等标准日期格式
  • 布尔值：复选框字段支持 true/false 字符串和布尔值转换

支持的操作

表操作
  • AutoMigrate() - 自动创建/更新表结构
  • CreateTable() - 创建表
  • DropTable() - 删除表
  • HasTable() - 检查表是否存在
记录操作
  • Create() - 创建记录
  • Find() - 查询记录
  • First() - 查询单条记录
  • Update() - 更新记录
  • Delete() - 删除记录
查询条件
  • Where() - 条件查询，支持多种操作符
  • Order() - 排序
  • Limit() - 限制数量
  • Offset() - 偏移量
支持的 SQL 操作符

BaseSQL 提供完整的 SQL 操作符支持，确保与飞书多维表格 API 的精确兼容：

比较操作符
  • = - 等于比较，适用于所有字段类型
  • > - 大于比较（数字、日期字段）
  • < - 小于比较（数字、日期字段）
  • >= - 大于等于比较（数字、日期字段）
  • <= - 小于等于比较（数字、日期字段）
-- 数字比较
SELECT * FROM users WHERE age > 18
SELECT * FROM products WHERE price <= 100.50

-- 日期比较
SELECT * FROM orders WHERE created_at >= '2024-01-01'
模式匹配
  • LIKE - 模式匹配，支持 % 通配符（文本字段）
  • 支持前缀、后缀、包含匹配
-- 包含匹配
SELECT * FROM users WHERE name LIKE '%张%'
-- 前缀匹配
SELECT * FROM users WHERE email LIKE 'admin%'
-- 后缀匹配
SELECT * FROM files WHERE filename LIKE '%.pdf'
集合操作
  • IN - 值在指定集合中
  • NOT IN - 值不在指定集合中
  • 支持多选、单选、人员等字段类型
-- 单选字段
SELECT * FROM users WHERE status IN ('active', 'pending')
-- 多选字段（检查是否包含指定值）
SELECT * FROM users WHERE skills IN ('Python', 'Go')
-- 人员字段
SELECT * FROM projects WHERE assignee IN ('张三', '李四')
空值检查
  • IS NULL - 字段为空或未设置
  • IS NOT NULL - 字段不为空且已设置
  • 适用于所有字段类型
-- 检查必填字段
SELECT * FROM users WHERE email IS NOT NULL
-- 查找未完成的任务
SELECT * FROM tasks WHERE completed_at IS NULL
布尔操作
  • = true - 复选框字段为真
  • = false - 复选框字段为假
  • 支持布尔值和字符串形式
-- 查找活跃用户
SELECT * FROM users WHERE is_active = true
-- 查找未验证用户
SELECT * FROM users WHERE email_verified = false
操作符兼容性
字段类型 = > < >= <= LIKE IN IS NULL 布尔值
单行文本 ✅ ❌ ✅ ✅ ✅ ❌
多行文本 ✅ ❌ ✅ ✅ ✅ ❌
数字 ✅ ✅ ❌ ✅ ✅ ❌
复选框 ✅ ❌ ❌ ❌ ✅ ✅
日期 ✅ ✅ ❌ ✅ ✅ ❌
链接 ✅ ❌ ✅ ✅ ✅ ❌
多选 ❌ ❌ ❌ ✅ ✅ ❌
单选 ✅ ❌ ❌ ✅ ✅ ❌
人员 ❌ ❌ ❌ ✅ ✅ ❌
使用示例
// 文本字段操作
db.Where("name = ?", "张三")
db.Where("name LIKE ?", "%张%")
db.Where("name IN ?", []string{"张三", "李四"})
db.Where("name IS NULL")

// 数字字段操作
db.Where("age = ?", 25)
db.Where("age > ?", 18)
db.Where("salary >= ?", 5000.0)
db.Where("age IN ?", []int{25, 30, 35})

// 布尔字段操作
db.Where("active = ?", true)
db.Where("active = ?", false)
db.Where("active IS NULL")

// 日期字段操作
db.Where("created_at > ?", time.Now().AddDate(0, -1, 0))
db.Where("birth_date IS NOT NULL")

// 多选字段操作
db.Where("skills IN ?", []string{"Go", "Python"})

// 人员字段操作
db.Where("manager = ?", "张三")
db.Where("manager IN ?", []string{"张三", "李四"})

配置选项

type Config struct {
    // 飞书应用配置
    AppID     string        // 飞书应用 ID
    AppSecret string        // 飞书应用密钥
    BaseURL   string        // API 基础 URL（可选，默认为官方 API）
    
    // 认证配置
    AuthType    AuthType      // 认证类型
    AccessToken string        // 用户访问令牌（用户认证时需要）
    
    // 多维表格配置
    AppToken string        // 多维表格 App Token
    TableID  string        // 默认表 ID（可选）
    
    // 连接配置
    Timeout         time.Duration // 请求超时时间（可选，默认 30 秒）
    MaxRetries      int           // 最大重试次数
    RetryInterval   time.Duration // 重试间隔
    RateLimitQPS    int           // 每秒请求限制
    BatchSize       int           // 批量操作大小
    CacheEnabled    bool          // 是否启用缓存
    CacheTTL        time.Duration // 缓存过期时间
    DebugMode       bool          // 调试模式（可选，开启后会打印详细日志）
    ConsistencyMode bool          // 一致性模式
    
    // 稳定性配置
    CircuitBreakerEnabled    bool          // 是否启用熔断器
    CircuitBreakerThreshold  int           // 熔断器失败阈值
    CircuitBreakerTimeout    time.Duration // 熔断器超时时间
    ConnectionPoolSize       int           // 连接池大小
    ConnectionPoolMaxIdle    int           // 连接池最大空闲连接数
    ConnectionPoolIdleTimeout time.Duration // 连接池空闲超时时间
    RateLimiterEnabled       bool          // 是否启用限流器
    RateLimiterBurst         int           // 限流器突发容量
}

注意事项

  1. 主键字段: 飞书多维表格的记录 ID 会自动映射为主键，建议使用 string 类型
  2. 字段命名: 建议使用英文字段名，避免特殊字符
  3. 数据类型: 某些复杂类型可能需要自定义转换
  4. 权限配置: 确保应用有足够的权限访问多维表格
  5. API 限制: 注意飞书 API 的调用频率限制
  6. 表名映射: GORM 会自动将结构体名转换为表名（如 User -> users）
  7. 字段映射: 使用 gorm 标签来控制字段映射和属性

稳定性功能

BaseSQL 内置了多种稳定性保障机制，确保在高并发和网络不稳定环境下的可靠性：

熔断器 (Circuit Breaker)

熔断器可以防止级联故障，当检测到大量失败请求时自动切断请求：

// 获取熔断器统计信息
stats := client.GetStabilityStats()
log.Printf("熔断器状态: %s, 失败次数: %d", stats.CircuitBreakerState, stats.CircuitBreakerFailures)

// 重置熔断器
client.ResetStabilityComponents()
连接池 (Connection Pool)

连接池管理 HTTP 连接，提高性能并控制资源使用：

// 更新连接池配置
newPoolConfig := &common.ConnectionPoolConfig{
    MaxConnections:    50,
    MaxIdleConns:      10,
    IdleConnTimeout:   time.Minute * 5,
    MaxConnLifetime:   time.Minute * 30,
}
client.UpdateConnectionPoolConfig(newPoolConfig)
限流器 (Rate Limiter)

基于令牌桶算法的限流器，防止请求过载：

// 更新限流器配置
newRateConfig := &common.RateLimiterConfig{
    Rate:       10,    // 每秒 10 个请求
    Burst:      20,    // 突发容量 20
    Enabled:    true,
}
client.UpdateRateLimiterConfig(newRateConfig)
健康检查

定期检查客户端和各组件的健康状态：

// 执行健康检查
if err := client.HealthCheck(); err != nil {
    log.Printf("健康检查失败: %v", err)
} else {
    log.Println("系统运行正常")
}
监控统计

获取详细的性能和稳定性统计信息：

stats := client.GetStabilityStats()
log.Printf("统计信息: %+v", stats)
// 输出包括：
// - 熔断器状态和统计
// - 连接池使用情况
// - 限流器统计
// - 请求成功/失败次数
// - 平均响应时间等

错误处理

BaseSQL 提供了丰富的错误处理机制：

if err := db.Create(&user).Error; err != nil {
    if basesql.IsPermissionError(err) {
        log.Println("权限不足，请检查应用权限配置")
        // 可能需要重新配置应用权限或检查 App Token
    } else if basesql.IsRetryableError(err) {
        log.Println("网络错误，可以重试")
        // 可以实现重试逻辑
        time.Sleep(time.Second)
        // 重试操作...
    } else {
        log.Printf("其他错误: %v", err)
        // 处理其他类型的错误
    }
}
常见错误类型
  • ErrConnectionFailed: 连接失败
  • ErrInvalidCredentials: 认证信息无效
  • ErrTableNotFound: 表不存在
  • ErrFieldNotFound: 字段不存在
  • ErrRecordNotFound: 记录不存在
  • ErrPermissionDenied: 权限不足
  • ErrRateLimitExceeded: 请求频率超限

常见问题

Q: 如何获取多维表格的 App Token？

A: 在飞书多维表格中，点击右上角的"..."菜单，选择"高级设置"，在"应用 Token"部分可以找到。

Q: 为什么提示权限不足？

A: 请确保：

  1. 应用已获得多维表格的读写权限
  2. App Token 对应的多维表格允许该应用访问
  3. 如果使用用户认证，确保用户有相应权限
Q: 支持事务吗？

A: 由于飞书多维表格 API 的限制，目前不支持传统意义上的事务。

Q: 如何处理大量数据？

A: 建议使用分页查询，并注意 API 调用频率限制。

Q: 如何优化高并发场景下的性能？

A: BaseSQL 提供了多种稳定性机制：

  1. 启用连接池来复用 HTTP 连接
  2. 使用限流器控制请求频率
  3. 配置熔断器防止级联故障
  4. 调整重试策略和超时时间
Q: 熔断器什么时候会触发？

A: 当连续失败次数达到配置的阈值时，熔断器会进入开启状态，暂时拒绝所有请求。经过一段时间后会进入半开状态进行探测。

Q: 如何监控系统运行状态？

A: 使用 client.GetStabilityStats() 获取详细统计信息，包括熔断器状态、连接池使用情况、限流器统计等。建议定期调用 client.HealthCheck() 进行健康检查。

示例项目

查看 example/ 目录中的完整示例代码，支持两种配置方式：

基本示例：

cd example

# 方式一：直接修改代码中的配置
# 编辑 main.go，替换为你的真实凭据
go run main.go

# 方式二：使用环境变量（推荐）
cp .env.example .env
# 编辑 .env 文件，填入你的配置
source .env  # 或者 export 各个变量
go run main.go

稳定性功能示例：

cd example

# 运行稳定性功能演示
# 编辑 stability_example.go，填入你的配置
go run stability_example.go

文档

许可证

MIT License

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrConnectionFailed   = errors.New("basesql: connection failed")
	ErrInvalidCredentials = errors.New("basesql: invalid credentials")
	ErrTableNotFound      = errors.New("basesql: table not found")
	ErrFieldNotFound      = errors.New("basesql: field not found")
	ErrRecordNotFound     = errors.New("basesql: record not found")
	ErrUnsupportedType    = errors.New("basesql: unsupported data type")
	ErrRateLimitExceeded  = errors.New("basesql: rate limit exceeded")
	ErrBatchSizeExceeded  = errors.New("basesql: batch size exceeded")
	ErrInvalidQuery       = errors.New("basesql: invalid query")
	ErrPermissionDenied   = errors.New("basesql: permission denied")
	ErrInvalidOperation   = errors.New("basesql: invalid operation")
)

预定义错误

View Source 
var DefaultRetryConfig = RetryConfig{
	MaxRetries:   3,
	InitialDelay: time.Second,
	MaxDelay:     30 * time.Second,
	Multiplier:   2.0,
}

DefaultRetryConfig 默认重试配置

View Source 
var FieldTypeMapping = map[FieldType]string{
	FieldTypeText:         "1",
	FieldTypeNumber:       "2",
	FieldTypeSingleSelect: "3",
	FieldTypeMultiSelect:  "4",
	FieldTypeDate:         "5",
	FieldTypeCheckbox:     "7",
	FieldTypeUser:         "11",
	FieldTypePhone:        "13",
	FieldTypeURL:          "15",
	FieldTypeAttachment:   "17",
	FieldTypeBarcode:      "18",
	FieldTypeProgress:     "19",
	FieldTypeCurrency:     "20",
	FieldTypeRating:       "21",
	FieldTypeFormula:      "22",
	FieldTypeLookup:       "23",
	FieldTypeCreatedTime:  "1001",
	FieldTypeModifiedTime: "1002",
	FieldTypeCreatedUser:  "1003",
	FieldTypeModifiedUser: "1004",
	FieldTypeAutoNumber:   "1005",
}

FieldTypeMapping 字段类型到字符串的映射表 用于 JSON 序列化时将字段类型枚举转换为对应的字符串表示

Functions

func ErrAPICall 

func ErrAPICall(details string) error

func ErrAuth 

func ErrAuth(details string) error

func ErrDataMapping 

func ErrDataMapping(details string) error

func ErrInvalidConfig 

func ErrInvalidConfig(details string) error

错误构造函数

func ErrSQLParsing 

func ErrSQLParsing(details string) error

func GetFieldTypeName 

func GetFieldTypeName(fieldType FieldType) string

GetFieldTypeName 获取字段类型的可读名称 参数:

  • fieldType: 字段类型枚举值

返回:

  • string: 字段类型的可读名称

func GetStringFromMap 

func GetStringFromMap(m map[string]interface{}, key string) string

GetStringFromMap 安全地从 map 中获取字符串值

func IsPermissionError 

func IsPermissionError(err error) bool

IsPermissionError 判断是否为权限错误

func IsValidFieldType 

func IsValidFieldType(fieldType FieldType) bool

IsValidFieldType 检查字段类型是否有效 参数:

  • fieldType: 要检查的字段类型

返回:

  • bool: 如果字段类型有效返回 true，否则返回 false

func Open 

func Open(config *Config) gorm.Dialector

Open 创建并返回一个新的 BaseSQL 方言器实例 该函数会合并用户配置和默认配置，确保所有必要的配置项都有合理的默认值 参数:

  • config: 用户提供的配置，可以为 nil 或部分配置

返回:

  • gorm.Dialector: GORM 方言器接口实例

func RegisterCallbacks 

func RegisterCallbacks(db *gorm.DB, dialector *Dialector)

RegisterCallbacks 注册 GORM 回调函数 这个函数会替换 GORM 的默认回调处理器，将 SQL 操作转换为飞书多维表格 API 调用 参数:

  • db: GORM 数据库实例
  • dialector: BaseSQL 的方言器实例

Types

type APIError 

type APIError = common.APIError

type APIRequest 

type APIRequest = common.APIRequest

使用公共工具包的 API 类型

type APIResponse 

type APIResponse = common.APIResponse

type AuthType 

type AuthType string

AuthType 认证类型 

const (
	// AuthTypeTenant 应用认证（tenant_access_token）
	AuthTypeTenant AuthType = "tenant"
	// AuthTypeUser 用户认证（user_access_token）
	AuthTypeUser AuthType = "user"
)

type BaseError 

type BaseError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Details string `json:"details,omitempty"`
}

BaseError 基础错误类型

func (*BaseError) Error 

func (e *BaseError) Error() string

type BaseValue 

type BaseValue struct {
	Val interface{} // 存储的值，可以是任意类型
}

BaseValue 实现了 GORM 和 SQL 相关的值接口 用于在 GORM 和飞书多维表格之间进行值的转换和传递

func NewBaseValue 

func NewBaseValue(val interface{}) *BaseValue

NewBaseValue 创建一个新的 BaseValue 实例 参数:

  • val: 要存储的值

返回:

  • *BaseValue: BaseValue 实例

func (BaseValue) GormValue 

func (v BaseValue) GormValue(ctx context.Context, db *gorm.DB) clause.Expr

GormValue 实现 gorm.Valuer 接口 将值转换为 GORM 可以处理的表达式 参数:

  • ctx: 上下文
  • db: GORM 数据库实例

返回:

  • clause.Expr: GORM 表达式

func (BaseValue) IsNil 

func (v BaseValue) IsNil() bool

IsNil 检查值是否为 nil 返回:

  • bool: 如果值为 nil 返回 true，否则返回 false

func (*BaseValue) Scan 

func (v *BaseValue) Scan(value interface{}) error

Scan 实现 sql.Scanner 接口 从数据库扫描值到结构体 参数:

  • value: 从数据库读取的值

返回:

  • error: 扫描过程中的错误

func (BaseValue) String 

func (v BaseValue) String() string

String 返回值的字符串表示 返回:

  • string: 值的字符串表示

func (BaseValue) Value 

func (v BaseValue) Value() (driver.Value, error)

Value 实现 driver.Valuer 接口 将值转换为数据库驱动可以处理的类型 返回:

  • driver.Value: 驱动值
  • error: 转换过程中的错误

type BatchCreateRecordsRequest 

type BatchCreateRecordsRequest struct {
	Records []*CreateRecordRequest `json:"records"` // 要创建的记录列表
}

BatchCreateRecordsRequest 批量创建记录的请求结构 用于一次性创建多条记录，提高操作效率

func (*BatchCreateRecordsRequest) Validate 

func (req *BatchCreateRecordsRequest) Validate() error

Validate 验证批量创建记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type BatchCreateRecordsResponse 

type BatchCreateRecordsResponse struct {
	Records []*Record `json:"records"` // 创建的记录列表
}

BatchCreateRecordsResponse 批量创建记录的响应结构 包含批量创建操作的结果和新创建的记录列表

func (*BatchCreateRecordsResponse) GetRecordCount 

func (resp *BatchCreateRecordsResponse) GetRecordCount() int

GetRecordCount 获取成功创建的记录数量 返回:

  • int: 成功创建的记录数量

func (*BatchCreateRecordsResponse) GetRecords 

func (resp *BatchCreateRecordsResponse) GetRecords() []*Record

GetRecords 获取创建的记录列表 返回:

  • []*Record: 创建的记录列表，如果操作失败返回空切片

func (*BatchCreateRecordsResponse) IsSuccess 

func (resp *BatchCreateRecordsResponse) IsSuccess() bool

IsSuccess 判断批量创建记录操作是否成功 返回:

  • bool: 操作是否成功

type BatchDeleteRecordsRequest 

type BatchDeleteRecordsRequest struct {
	Records []string `json:"records"` // 要删除的记录 ID 列表
}

BatchDeleteRecordsRequest 批量删除记录的请求结构 用于一次性删除多条记录

func (*BatchDeleteRecordsRequest) Validate 

func (req *BatchDeleteRecordsRequest) Validate() error

Validate 验证批量删除记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type BatchDeleteRecordsResponse 

type BatchDeleteRecordsResponse struct {
	Records []string `json:"records"` // 成功删除的记录 ID 列表
}

BatchDeleteRecordsResponse 批量删除记录的响应结构 包含批量删除操作的结果

func (*BatchDeleteRecordsResponse) GetDeletedCount 

func (resp *BatchDeleteRecordsResponse) GetDeletedCount() int

GetDeletedCount 获取成功删除的记录数量 返回:

  • int: 成功删除的记录数量

func (*BatchDeleteRecordsResponse) GetDeletedRecords 

func (resp *BatchDeleteRecordsResponse) GetDeletedRecords() []string

GetDeletedRecords 获取成功删除的记录 ID 列表 返回:

  • []string: 成功删除的记录 ID 列表

func (*BatchDeleteRecordsResponse) IsSuccess 

func (resp *BatchDeleteRecordsResponse) IsSuccess() bool

IsSuccess 判断批量删除记录操作是否成功 返回:

  • bool: 操作是否成功

type BatchUpdateRecord 

type BatchUpdateRecord struct {
	RecordID string                 `json:"record_id"` // 要更新的记录 ID
	Fields   map[string]interface{} `json:"fields"`    // 要更新的字段值映射
}

BatchUpdateRecord 批量更新记录项 表示单个要更新的记录及其新的字段值

func (*BatchUpdateRecord) Validate 

func (r *BatchUpdateRecord) Validate() error

Validate 验证批量更新记录项的有效性 返回:

  • error: 如果记录项无效，返回相应的错误信息

type BatchUpdateRecordsRequest 

type BatchUpdateRecordsRequest struct {
	Records []*BatchUpdateRecord `json:"records"` // 要更新的记录列表
}

BatchUpdateRecordsRequest 批量更新记录的请求结构 用于一次性更新多条记录，提高操作效率

func (*BatchUpdateRecordsRequest) Validate 

func (req *BatchUpdateRecordsRequest) Validate() error

Validate 验证批量更新记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type BatchUpdateRecordsResponse 

type BatchUpdateRecordsResponse struct {
	Records []*Record `json:"records"` // 更新后的记录列表
}

BatchUpdateRecordsResponse 批量更新记录的响应结构 包含批量更新操作的结果和更新后的记录列表

func (*BatchUpdateRecordsResponse) GetRecordCount 

func (resp *BatchUpdateRecordsResponse) GetRecordCount() int

GetRecordCount 获取成功更新的记录数量 返回:

  • int: 成功更新的记录数量

func (*BatchUpdateRecordsResponse) GetRecords 

func (resp *BatchUpdateRecordsResponse) GetRecords() []*Record

GetRecords 获取更新后的记录列表 返回:

  • []*Record: 更新后的记录列表，如果操作失败返回空切片

func (*BatchUpdateRecordsResponse) IsSuccess 

func (resp *BatchUpdateRecordsResponse) IsSuccess() bool

IsSuccess 判断批量更新记录操作是否成功 返回:

  • bool: 操作是否成功

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client 飞书 API 客户端，负责处理与飞书多维表格 API 的所有通信 包括认证、令牌管理、请求发送等核心功能

func NewClient 

func NewClient(config *Config) (*Client, error)

NewClient 创建新的飞书 API 客户端 参数:

  • config: 客户端配置，包含认证信息和其他设置

返回:

  • *Client: 初始化完成的客户端实例
  • error: 创建过程中的错误

func (*Client) Close 

func (c *Client) Close() error

Close 关闭客户端并清理资源 这个方法是幂等的，可以安全地多次调用

func (*Client) DoRequest 

func (c *Client) DoRequest(ctx context.Context, req *APIRequest) (*APIResponse, error)

DoRequest 执行飞书 API 请求 这是所有 API 调用的核心方法，处理认证、请求构建、发送和响应解析 支持自动重试机制，提高请求的稳定性 参数:

  • ctx: 上下文，用于控制请求超时和取消
  • req: API 请求结构，包含请求的所有信息

返回:

  • *APIResponse: API 响应结构
  • error: 请求过程中的错误

func (*Client) GetStabilityStats 

func (c *Client) GetStabilityStats() map[string]interface{}

GetStabilityStats 获取稳定性组件统计信息 返回:

  • map[string]interface{}: 统计信息

func (*Client) HealthCheck 

func (c *Client) HealthCheck(ctx context.Context) (bool, error)

HealthCheck 执行健康检查 参数:

  • ctx: 上下文

返回:

  • bool: 是否健康
  • error: 检查错误

func (*Client) ResetStabilityComponents 

func (c *Client) ResetStabilityComponents() error

ResetStabilityComponents 重置稳定性组件 返回:

  • error: 重置错误

func (*Client) SetRetryConfig 

func (c *Client) SetRetryConfig(config *RetryConfig)

SetRetryConfig 设置重试配置 参数:

  • config: 重试配置

func (*Client) UpdateConnectionPoolConfig 

func (c *Client) UpdateConnectionPoolConfig(config *common.ConnectionPoolConfig) error

UpdateConnectionPoolConfig 更新连接池配置 参数:

  • config: 新的连接池配置

返回:

  • error: 更新错误

func (*Client) UpdateRateLimiterConfig 

func (c *Client) UpdateRateLimiterConfig(config *common.RateLimiterConfig) error

UpdateRateLimiterConfig 更新限流器配置 参数:

  • config: 新的限流器配置

返回:

  • error: 更新错误

type Config 

type Config struct {
	// 飞书应用配置
	AppID     string `json:"app_id"`     // 应用 ID
	AppSecret string `json:"app_secret"` // 应用密钥
	BaseURL   string `json:"base_url"`   // API 基础 URL，默认 https://open.feishu.cn

	// 认证配置
	AuthType    AuthType `json:"auth_type"`    // 认证类型
	AccessToken string   `json:"access_token"` // 用户访问令牌（AuthTypeUser 时使用）

	// 多维表格配置
	AppToken string `json:"app_token"` // 多维表格的 app_token
	TableID  string `json:"table_id"`  // 默认表 ID（可选）

	// 连接配置
	Timeout         time.Duration `json:"timeout"`          // 请求超时时间
	MaxRetries      int           `json:"max_retries"`      // 最大重试次数
	RetryInterval   time.Duration `json:"retry_interval"`   // 重试间隔
	RateLimitQPS    int           `json:"rate_limit_qps"`   // 每秒请求限制
	BatchSize       int           `json:"batch_size"`       // 批量操作大小
	CacheEnabled    bool          `json:"cache_enabled"`    // 是否启用缓存
	CacheTTL        time.Duration `json:"cache_ttl"`        // 缓存过期时间
	DebugMode       bool          `json:"debug_mode"`       // 调试模式
	ConsistencyMode bool          `json:"consistency_mode"` // 一致性模式
}

Config 飞书多维表格配置

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig 返回默认配置

func (*Config) Clone 

func (c *Config) Clone() *Config

Clone 克隆配置

func (*Config) Validate 

func (c *Config) Validate() error

Validate 验证配置

type ConnPool 

type ConnPool struct {
	Dialector *Dialector // 关联的方言器实例
}

ConnPool 实现 gorm.ConnPool 接口 用于拦截 GORM 的数据库操作，将其转换为飞书多维表格 API 调用 注意：由于飞书多维表格不是传统的 SQL 数据库，大部分方法返回不支持的错误

func (*ConnPool) BeginTx 

func (c *ConnPool) BeginTx(ctx context.Context, opt *sql.TxOptions) (gorm.ConnPool, error)

BeginTx 开始事务 实现 gorm.ConnPoolBeginner 接口 由于飞书多维表格不支持事务，此方法返回一个Transaction实例 参数:

  • ctx: 上下文
  • opt: 事务选项

返回:

  • gorm.ConnPool: Transaction实例（实现了gorm.ConnPool接口）
  • error: 错误信息（始终为 nil）

func (*ConnPool) ExecContext 

func (c *ConnPool) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext 执行 SQL 语句 由于飞书多维表格不支持直接 SQL 执行，此方法返回不支持错误 实际的操作通过 GORM 回调函数处理 参数:

  • ctx: 上下文
  • query: SQL 查询语句
  • args: 查询参数

返回:

  • sql.Result: 执行结果（始终为 nil）
  • error: 不支持错误

func (*ConnPool) PrepareContext 

func (c *ConnPool) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)

PrepareContext 准备 SQL 语句 由于飞书多维表格不支持预编译语句，此方法返回不支持错误 参数:

  • ctx: 上下文
  • query: SQL 查询语句

返回:

  • *sql.Stmt: 预编译语句（始终为 nil）
  • error: 不支持错误

func (*ConnPool) QueryContext 

func (c *ConnPool) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext 执行查询语句 由于飞书多维表格不支持直接 SQL 查询，此方法返回不支持错误 实际的查询通过 GORM 回调函数处理 参数:

  • ctx: 上下文
  • query: SQL 查询语句
  • args: 查询参数

返回:

  • *sql.Rows: 查询结果（始终为 nil）
  • error: 不支持错误

func (*ConnPool) QueryRowContext 

func (c *ConnPool) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRowContext 执行单行查询 由于飞书多维表格不支持直接 SQL 查询，此方法返回空行 实际的查询通过 GORM 回调函数处理 参数:

  • ctx: 上下文
  • query: SQL 查询语句
  • args: 查询参数

返回:

  • *sql.Row: 查询结果行（空行）

func (*ConnPool) RollbackTo 

func (c *ConnPool) RollbackTo(ctx context.Context, name string) error

RollbackTo 回滚到保存点 实现 gorm.SavePointer 接口 由于飞书多维表格不支持事务回滚，此方法为空实现 参数:

  • ctx: 上下文
  • name: 保存点名称

返回:

  • error: 错误信息（始终为 nil）

func (*ConnPool) SavePoint 

func (c *ConnPool) SavePoint(ctx context.Context, name string) error

SavePoint 创建保存点 实现 gorm.SavePointer 接口 由于飞书多维表格不支持事务保存点，此方法为空实现 参数:

  • ctx: 上下文
  • name: 保存点名称

返回:

  • error: 错误信息（始终为 nil）

type CreateDefaultViewRequest 

type CreateDefaultViewRequest struct {
	Name     string `json:"name"`      // 视图名称
	ViewType string `json:"view_type"` // 视图类型（如 grid、kanban 等）
}

CreateDefaultViewRequest 创建默认视图的请求结构 用于为新创建的表设置默认视图

func (*CreateDefaultViewRequest) Validate 

func (req *CreateDefaultViewRequest) Validate() error

Validate 验证创建默认视图请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type CreateFieldRequest 

type CreateFieldRequest struct {
	FieldName   string                 `json:"field_name"`            // 字段名称
	Type        FieldType              `json:"type"`                  // 字段类型
	Property    map[string]interface{} `json:"property,omitempty"`    // 字段属性配置
	Description string                 `json:"description,omitempty"` // 字段描述
}

CreateFieldRequest 创建字段的请求结构 用于在飞书多维表格中创建新字段

func (*CreateFieldRequest) MarshalJSON 

func (r *CreateFieldRequest) MarshalJSON() ([]byte, error)

MarshalJSON 自定义 JSON 序列化 将 FieldType 枚举转换为整数类型以符合 API 要求

func (*CreateFieldRequest) Validate 

func (req *CreateFieldRequest) Validate() error

Validate 验证创建字段请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type CreateFieldResponse 

type CreateFieldResponse struct {
	Field *Field `json:"field"` // 创建的字段信息
}

CreateFieldResponse 创建字段的响应结构 包含创建操作的结果和新创建的字段信息

func (*CreateFieldResponse) GetField 

func (resp *CreateFieldResponse) GetField() *Field

GetField 获取创建的字段 返回:

  • *Field: 创建的字段，如果操作失败返回 nil

func (*CreateFieldResponse) IsSuccess 

func (resp *CreateFieldResponse) IsSuccess() bool

IsSuccess 判断创建字段操作是否成功 返回:

  • bool: 操作是否成功

type CreateRecordAPIResponse 

type CreateRecordAPIResponse struct {
	Code int                   `json:"code"` // 响应码
	Msg  string                `json:"msg"`  // 响应消息
	Data *CreateRecordResponse `json:"data"` // 实际数据
}

CreateRecordAPIResponse 飞书API创建记录的完整响应结构 包含飞书API标准的code、data、msg字段

type CreateRecordRequest 

type CreateRecordRequest struct {
	Fields map[string]interface{} `json:"fields"` // 记录的字段值映射
}

CreateRecordRequest 创建记录的请求结构 用于向飞书多维表格创建新记录

func (*CreateRecordRequest) Validate 

func (req *CreateRecordRequest) Validate() error

Validate 验证创建记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type CreateRecordResponse 

type CreateRecordResponse struct {
	Record *Record `json:"record"` // 创建的记录信息
}

CreateRecordResponse 创建记录的响应结构 包含创建操作的结果和新创建的记录信息

type CreateTableRequest 

type CreateTableRequest struct {
	Table *TableRequest `json:"table"` // 表的详细信息
}

CreateTableRequest 创建表的请求结构 用于在飞书多维表格中创建新的数据表

func (*CreateTableRequest) Validate 

func (req *CreateTableRequest) Validate() error

Validate 验证创建表请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type CreateTableResponse 

type CreateTableResponse struct {
	TableID       string `json:"table_id"`        // 创建的表 ID
	DefaultViewID string `json:"default_view_id"` // 默认视图 ID
}

CreateTableResponse 创建数据表的响应结构 包含创建操作的结果和新创建的表信息

func (*CreateTableResponse) GetDefaultViewID 

func (resp *CreateTableResponse) GetDefaultViewID() string

GetDefaultViewID 获取默认视图 ID 返回:

  • string: 默认视图 ID

func (*CreateTableResponse) GetTableID 

func (resp *CreateTableResponse) GetTableID() string

GetTableID 获取创建的表 ID 返回:

  • string: 表 ID

func (*CreateTableResponse) IsSuccess 

func (resp *CreateTableResponse) IsSuccess() bool

IsSuccess 判断创建表操作是否成功 返回:

  • bool: 操作是否成功

type Dialector 

type Dialector struct {
	*Config         // 配置信息，包含认证、超时、重试等设置
	Client  *Client // 飞书 API 客户端实例
}

Dialector 实现了 GORM 的方言器接口，用于将 GORM 操作转换为飞书多维表格 API 调用 它包含了配置信息和客户端实例，是整个驱动的核心组件

func (*Dialector) BindVarTo 

func (d *Dialector) BindVarTo(writer clause.Writer, stmt *gorm.Statement, v interface{})

BindVarTo 写入绑定变量占位符 实现 gorm.Dialector 接口的 BindVarTo 方法 参数:

  • writer: 子句写入器
  • stmt: GORM 语句
  • v: 绑定的值

func (*Dialector) DataTypeOf 

func (d *Dialector) DataTypeOf(field *schema.Field) string

DataTypeOf 将 GORM 字段类型转换为飞书多维表格字段类型 实现 gorm.Dialector 接口的 DataTypeOf 方法 参数:

  • field: GORM 字段定义

返回:

  • string: 对应的飞书多维表格字段类型

func (*Dialector) DefaultValueOf 

func (d *Dialector) DefaultValueOf(field *schema.Field) clause.Expression

DefaultValueOf 返回字段的默认值表达式 实现 gorm.Dialector 接口的 DefaultValueOf 方法 参数:

  • field: GORM 字段定义

返回:

  • clause.Expression: 默认值表达式

func (*Dialector) Explain 

func (d *Dialector) Explain(sql string, vars ...interface{}) string

Explain 解释 SQL 语句，用于调试和日志记录 实现 gorm.Dialector 接口的 Explain 方法 参数:

  • sql: SQL 语句
  • vars: 绑定变量

返回:

  • string: 解释后的 SQL 语句

func (*Dialector) Initialize 

func (d *Dialector) Initialize(db *gorm.DB) error

Initialize 初始化方言器 该方法会创建飞书 API 客户端、设置连接池并注册回调函数 参数:

  • db: GORM 数据库实例

返回:

  • error: 初始化过程中的错误

func (*Dialector) Migrator 

func (d *Dialector) Migrator(db *gorm.DB) gorm.Migrator

Migrator 返回数据库迁移器实例 实现 gorm.Dialector 接口的 Migrator 方法 参数:

  • db: GORM 数据库实例

返回:

  • gorm.Migrator: 迁移器实例

func (*Dialector) Name 

func (d *Dialector) Name() string

Name 返回方言器的名称 实现 gorm.Dialector 接口的 Name 方法 返回:

  • string: 方言器名称 "basesql"

func (*Dialector) QuoteTo 

func (d *Dialector) QuoteTo(writer clause.Writer, str string)

QuoteTo 写入带引号的标识符 实现 gorm.Dialector 接口的 QuoteTo 方法 参数:

  • writer: 子句写入器
  • str: 要引用的字符串

type Field 

type Field struct {
	FieldID     string                 `json:"field_id"`    // 字段的唯一标识符
	FieldName   string                 `json:"field_name"`  // 字段名称
	Type        FieldType              `json:"type"`        // 字段类型
	Property    map[string]interface{} `json:"property"`    // 字段属性配置（如选项列表、格式设置等）
	Description string                 `json:"description"` // 字段描述
	IsPrimary   bool                   `json:"is_primary"`  // 是否为主键字段
}

Field 飞书多维表格的字段结构 表示表中的一个字段，包含字段的所有属性和配置信息

func (*Field) ConvertFromGoValue 

func (f *Field) ConvertFromGoValue(value interface{}) interface{}

ConvertFromGoValue 将 Go 语言标准类型转换为飞书多维表格字段值 该方法将 Go 类型转换为飞书 API 期望的格式，确保数据能正确提交到飞书 参数:

  • value: Go 语言类型的值

返回:

  • interface{}: 转换后的飞书 API 格式值，转换失败时返回 nil 或对应类型的零值

func (*Field) ConvertToGoValue 

func (f *Field) ConvertToGoValue(value interface{}) interface{}

ConvertToGoValue 将飞书多维表格字段值转换为 Go 语言标准类型 该方法提供了类型安全的转换，支持多种数据类型的智能转换 参数:

  • value: 来自飞书 API 的原始字段值

返回:

  • interface{}: 转换后的 Go 语言类型值，转换失败时返回对应类型的零值

func (*Field) IsReadOnly 

func (f *Field) IsReadOnly() bool

IsReadOnly 判断字段是否为只读 返回:

  • bool: 如果字段只读返回 true，否则返回 false

func (*Field) IsSystemField 

func (f *Field) IsSystemField() bool

IsSystemField 判断是否为系统字段 返回:

  • bool: 如果是系统字段返回 true，否则返回 false

func (*Field) MarshalJSON 

func (f *Field) MarshalJSON() ([]byte, error)

MarshalJSON 自定义 JSON 序列化

func (*Field) UnmarshalJSON 

func (f *Field) UnmarshalJSON(data []byte) error

UnmarshalJSON 自定义 JSON 反序列化

func (*Field) Validate 

func (f *Field) Validate() error

Validate 验证字段结构的有效性 返回:

  • error: 如果字段结构无效，返回相应的错误信息

type FieldType 

type FieldType int

FieldType 飞书多维表格字段类型枚举 定义了飞书多维表格支持的所有字段类型，每个类型对应一个唯一的数字标识 

const (
	FieldTypeText         FieldType = 1    // 多行文本字段
	FieldTypeNumber       FieldType = 2    // 数字字段
	FieldTypeSingleSelect FieldType = 3    // 单选字段
	FieldTypeMultiSelect  FieldType = 4    // 多选字段
	FieldTypeDate         FieldType = 5    // 日期字段
	FieldTypeCheckbox     FieldType = 7    // 复选框字段
	FieldTypeUser         FieldType = 11   // 人员字段
	FieldTypePhone        FieldType = 13   // 电话号码字段
	FieldTypeURL          FieldType = 15   // 超链接字段
	FieldTypeAttachment   FieldType = 17   // 附件字段
	FieldTypeBarcode      FieldType = 18   // 条码字段
	FieldTypeProgress     FieldType = 19   // 进度字段
	FieldTypeCurrency     FieldType = 20   // 货币字段
	FieldTypeRating       FieldType = 21   // 评分字段
	FieldTypeFormula      FieldType = 22   // 公式字段
	FieldTypeLookup       FieldType = 23   // 查找引用字段
	FieldTypeCreatedTime  FieldType = 1001 // 创建时间字段（系统字段）
	FieldTypeModifiedTime FieldType = 1002 // 最后更新时间字段（系统字段）
	FieldTypeCreatedUser  FieldType = 1003 // 创建人字段（系统字段）
	FieldTypeModifiedUser FieldType = 1004 // 修改人字段（系统字段）
	FieldTypeAutoNumber   FieldType = 1005 // 自动编号字段（系统字段）
)

飞书多维表格支持的字段类型常量定义 这些常量与飞书 API 文档中的字段类型编号保持一致

type FilterCondition 

type FilterCondition struct {
	FieldName string        `json:"field_name"` // 字段名称
	Operator  string        `json:"operator"`   // 操作符（如 is、contains、isEmpty 等）
	Value     []interface{} `json:"value"`      // 过滤值列表，支持不同类型
}

FilterCondition 过滤条件结构 用于定义记录查询时的过滤条件

func (*FilterCondition) Validate 

func (fc *FilterCondition) Validate() error

Validate 验证过滤条件的有效性 返回:

  • error: 如果过滤条件无效，返回相应的错误信息

type FilterRequest 

type FilterRequest struct {
	Conjunction string             `json:"conjunction"` // 连接符（and 或 or）
	Conditions  []*FilterCondition `json:"conditions"`  // 过滤条件列表
}

FilterRequest 过滤请求结构 用于组合多个过滤条件进行复杂查询

func (*FilterRequest) Validate 

func (fr *FilterRequest) Validate() error

Validate 验证过滤请求的有效性 返回:

  • error: 如果过滤请求无效，返回相应的错误信息

type ListFieldsAPIResponse 

type ListFieldsAPIResponse struct {
	Code int                 `json:"code"` // 响应码
	Msg  string              `json:"msg"`  // 响应消息
	Data *ListFieldsResponse `json:"data"` // 实际数据
}

ListFieldsAPIResponse 飞书API查询字段的完整响应结构 包含飞书API标准的code、data、msg字段

type ListFieldsResponse 

type ListFieldsResponse struct {
	Items []*Field `json:"items"` // 字段列表
}

ListFieldsResponse 查询字段的响应结构 包含表中所有字段的列表

func (*ListFieldsResponse) GetFieldByID 

func (resp *ListFieldsResponse) GetFieldByID(fieldID string) *Field

GetFieldByID 根据字段 ID 获取字段 参数:

  • fieldID: 字段 ID

返回:

  • *Field: 找到的字段，如果未找到返回 nil

func (*ListFieldsResponse) GetFieldByName 

func (resp *ListFieldsResponse) GetFieldByName(fieldName string) *Field

GetFieldByName 根据字段名称获取字段 参数:

  • fieldName: 字段名称

返回:

  • *Field: 找到的字段，如果未找到返回 nil

func (*ListFieldsResponse) GetFieldCount 

func (resp *ListFieldsResponse) GetFieldCount() int

GetFieldCount 获取字段数量 返回:

  • int: 字段数量

func (*ListFieldsResponse) GetFields 

func (resp *ListFieldsResponse) GetFields() []*Field

GetFields 获取字段列表 返回:

  • []*Field: 字段列表，如果操作失败返回空切片

func (*ListFieldsResponse) IsSuccess 

func (resp *ListFieldsResponse) IsSuccess() bool

IsSuccess 判断查询字段操作是否成功 返回:

  • bool: 操作是否成功

type ListRecordsAPIResponse 

type ListRecordsAPIResponse struct {
	Code int                  `json:"code"` // 响应码
	Msg  string               `json:"msg"`  // 响应消息
	Data *ListRecordsResponse `json:"data"` // 实际数据
}

ListRecordsAPIResponse 飞书API列表记录的完整响应结构 包含飞书API标准的code、data、msg字段

type ListRecordsRequest 

type ListRecordsRequest struct {
	ViewID           string         `json:"view_id,omitempty"`             // 视图 ID，指定查询的视图
	Filter           *FilterRequest `json:"filter,omitempty"`              // 过滤条件
	Sort             []string       `json:"sort,omitempty"`                // 排序条件
	FieldNames       []string       `json:"field_names,omitempty"`         // 指定返回的字段名列表
	TextFieldAsArray bool           `json:"text_field_as_array,omitempty"` // 文本字段是否以数组形式返回
	UserIDType       string         `json:"user_id_type,omitempty"`        // 用户 ID 类型
	DisplayFormula   bool           `json:"display_formula,omitempty"`     // 是否显示公式
	AutomaticFields  bool           `json:"automatic_fields,omitempty"`    // 是否包含自动字段
	PageToken        string         `json:"page_token,omitempty"`          // 分页标记
	PageSize         int            `json:"page_size,omitempty"`           // 每页记录数，最大 500
}

ListRecordsRequest 列表记录的请求结构 用于查询飞书多维表格中的记录列表

func (*ListRecordsRequest) Validate 

func (req *ListRecordsRequest) Validate() error

Validate 验证列表记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type ListRecordsResponse 

type ListRecordsResponse struct {
	HasMore   bool      `json:"has_more"`   // 是否还有更多数据
	PageToken string    `json:"page_token"` // 下一页的分页标记
	Total     int       `json:"total"`      // 总记录数
	Items     []*Record `json:"items"`      // 记录列表
}

ListRecordsResponse 列表记录的响应结构 包含查询到的记录列表和分页信息

func (*ListRecordsResponse) GetRecords 

func (resp *ListRecordsResponse) GetRecords() []*Record

GetRecords 获取记录列表 返回:

  • []*Record: 记录列表，如果没有数据返回空切片

func (*ListRecordsResponse) IsSuccess 

func (resp *ListRecordsResponse) IsSuccess() bool

IsSuccess 判断列表记录操作是否成功 返回:

  • bool: 操作是否成功

type ListTablesAPIResponse 

type ListTablesAPIResponse struct {
	Code int                 `json:"code"` // 响应码
	Msg  string              `json:"msg"`  // 响应消息
	Data *ListTablesResponse `json:"data"` // 实际数据
}

ListTablesAPIResponse 飞书API查询数据表的完整响应结构 包含飞书API标准的code、data、msg字段

type ListTablesResponse 

type ListTablesResponse struct {
	HasMore   bool     `json:"has_more"`   // 是否还有更多数据
	PageToken string   `json:"page_token"` // 下一页的分页标记
	Total     int      `json:"total"`      // 总记录数
	Items     []*Table `json:"items"`      // 表列表
}

ListTablesResponse 查询数据表的响应结构 包含多维表格中所有表的列表

func (*ListTablesResponse) GetTableByID 

func (resp *ListTablesResponse) GetTableByID(tableID string) *Table

GetTableByID 根据表 ID 获取表 参数:

  • tableID: 表 ID

返回:

  • *Table: 找到的表，如果未找到返回 nil

func (*ListTablesResponse) GetTableByName 

func (resp *ListTablesResponse) GetTableByName(tableName string) *Table

GetTableByName 根据表名称获取表 参数:

  • tableName: 表名称

返回:

  • *Table: 找到的表，如果未找到返回 nil

func (*ListTablesResponse) GetTableCount 

func (resp *ListTablesResponse) GetTableCount() int

GetTableCount 获取表数量 返回:

  • int: 表数量

func (*ListTablesResponse) GetTables 

func (resp *ListTablesResponse) GetTables() []*Table

GetTables 获取表列表 返回:

  • []*Table: 表列表，如果操作失败返回空切片

func (*ListTablesResponse) IsSuccess 

func (resp *ListTablesResponse) IsSuccess() bool

IsSuccess 判断查询表操作是否成功 返回:

  • bool: 操作是否成功

type Migrator 

type Migrator struct {
	*Dialector
	migrator.Migrator
}

func (Migrator) AutoMigrate 

func (m Migrator) AutoMigrate(values ...interface{}) error

AutoMigrate 自动迁移表结构

func (Migrator) CreateTable 

func (m Migrator) CreateTable(values ...interface{}) error

CreateTable 创建表

func (Migrator) DropTable 

func (m Migrator) DropTable(values ...interface{}) error

DropTable 删除表

func (Migrator) HasTable 

func (m Migrator) HasTable(table interface{}) bool

HasTable 检查表是否存在

func (Migrator) RunAutoMigrate 

func (m Migrator) RunAutoMigrate(value interface{}) error

RunAutoMigrate 执行自动迁移

func (Migrator) UpdateColumns 

func (m Migrator) UpdateColumns(value interface{}) error

UpdateColumns 更新列

type Option 

type Option struct {
	ID    string `json:"id"`    // 选项的唯一标识符
	Name  string `json:"name"`  // 选项名称
	Color int    `json:"color"` // 选项颜色代码
}

Option 飞书多维表格的选项结构 用于单选、多选等字段类型的选项定义

func (*Option) Validate 

func (o *Option) Validate() error

Validate 验证选项结构的有效性 返回:

  • error: 如果选项结构无效，返回相应的错误信息

type Record 

type Record struct {
	RecordID       string                 `json:"record_id"`        // 记录的唯一标识符
	Fields         map[string]interface{} `json:"fields"`           // 记录的字段值映射，key 为字段名，value 为字段值
	CreatedTime    int64                  `json:"created_time"`     // 记录创建时间（毫秒时间戳）
	LastModified   int64                  `json:"last_modified"`    // 记录最后修改时间（毫秒时间戳）
	CreatedBy      *User                  `json:"created_by"`       // 记录创建者信息
	LastModifiedBy *User                  `json:"last_modified_by"` // 记录最后修改者信息
}

Record 飞书多维表格的记录结构 表示表中的一条数据记录，包含记录的所有字段值和元数据信息

func (*Record) GetCreatedTime 

func (r *Record) GetCreatedTime() time.Time

GetCreatedTime 获取记录创建时间 返回:

  • time.Time: 创建时间

func (*Record) GetFieldValue 

func (r *Record) GetFieldValue(fieldName string) (interface{}, bool)

GetFieldValue 获取指定字段的值 参数:

  • fieldName: 字段名称

返回:

  • interface{}: 字段值，如果字段不存在返回 nil
  • bool: 字段是否存在

func (*Record) GetLastModified 

func (r *Record) GetLastModified() time.Time

GetLastModified 获取记录最后修改时间 返回:

  • time.Time: 最后修改时间

func (*Record) SetFieldValue 

func (r *Record) SetFieldValue(fieldName string, value interface{})

SetFieldValue 设置指定字段的值 参数:

  • fieldName: 字段名称
  • value: 字段值

func (*Record) Validate 

func (r *Record) Validate() error

Validate 验证记录结构的有效性 返回:

  • error: 如果记录结构无效，返回相应的错误信息

type RetryConfig 

type RetryConfig = common.RetryConfig

使用公共工具包的 RetryConfig 类型

type SQLCommand 

type SQLCommand = common.SQLCommand

使用公共的 SQLCommand 类型

type SQLConverter 

type SQLConverter struct {
	// contains filtered or unexported fields
}

SQLConverter SQL 转换器 负责将 GORM 的 SQL 语句转换为飞书多维表格 API 调用 支持 CREATE、SELECT、UPDATE、DELETE 等基本操作

func NewSQLConverter 

func NewSQLConverter(client *Client, config *Config) *SQLConverter

NewSQLConverter 创建 SQL 转换器实例 参数:

  • client: 已初始化的飞书 API 客户端
  • config: 配置信息

返回:

  • *SQLConverter: SQL 转换器实例

func (*SQLConverter) ConvertCreate 

func (c *SQLConverter) ConvertCreate(ctx context.Context, stmt *gorm.Statement) error

ConvertCreate 转换 CREATE 语句为飞书多维表格的创建记录 API 调用 参数:

  • ctx: 上下文，用于控制请求超时和取消
  • stmt: GORM 语句对象，包含要创建的数据信息

返回:

  • error: 转换或执行过程中的错误

func (*SQLConverter) ConvertDelete 

func (c *SQLConverter) ConvertDelete(ctx context.Context, stmt *gorm.Statement) error

ConvertDelete 转换 DELETE 语句为飞书多维表格的删除记录 API 调用 参数:

  • ctx: 上下文，用于控制请求超时和取消
  • stmt: GORM 语句对象，包含删除条件信息

返回:

  • error: 转换或执行过程中的错误

func (*SQLConverter) ConvertQuery 

func (c *SQLConverter) ConvertQuery(ctx context.Context, stmt *gorm.Statement) error

ConvertQuery 转换 SELECT 语句为飞书多维表格的查询记录 API 调用 支持字段选择、WHERE 条件过滤、ORDER BY 排序等功能 参数:

  • ctx: 上下文，用于控制请求超时和取消
  • stmt: GORM 语句对象，包含查询条件和字段信息

返回:

  • error: 转换或执行过程中的错误

func (*SQLConverter) ConvertUpdate 

func (c *SQLConverter) ConvertUpdate(ctx context.Context, stmt *gorm.Statement) error

ConvertUpdate 转换 UPDATE 语句为飞书多维表格的更新记录 API 调用 参数:

  • ctx: 上下文，用于控制请求超时和取消
  • stmt: GORM 语句对象，包含更新条件和字段信息

返回:

  • error: 转换或执行过程中的错误

type Table 

type Table struct {
	TableID  string   `json:"table_id"` // 表的唯一标识符
	Name     string   `json:"name"`     // 表名称
	Revision int64    `json:"revision"` // 表的版本号，用于并发控制
	Fields   []*Field `json:"fields"`   // 表中的所有字段列表
}

Table 飞书多维表格的数据表结构 表示一个完整的数据表，包含表的基本信息和所有字段定义

func (*Table) GetFieldByID 

func (t *Table) GetFieldByID(fieldID string) *Field

GetFieldByID 根据字段 ID 获取字段 参数:

  • fieldID: 字段 ID

返回:

  • *Field: 找到的字段，如果未找到返回 nil

func (*Table) GetFieldByName 

func (t *Table) GetFieldByName(fieldName string) *Field

GetFieldByName 根据字段名称获取字段 参数:

  • fieldName: 字段名称

返回:

  • *Field: 找到的字段，如果未找到返回 nil

func (*Table) Validate 

func (t *Table) Validate() error

Validate 验证表结构的有效性 返回:

  • error: 如果表结构无效，返回相应的错误信息

type TableRequest 

type TableRequest struct {
	Name            string                `json:"name"`                        // 表名称
	DefaultViewName string                `json:"default_view_name,omitempty"` // 默认视图名称
	Fields          []*CreateFieldRequest `json:"fields"`                      // 字段列表
}

TableRequest 表请求结构 包含创建表所需的所有信息

func (*TableRequest) Validate 

func (req *TableRequest) Validate() error

Validate 验证表请求的有效性 返回:

  • error: 如果表请求无效，返回相应的错误信息

type TokenResponse 

type TokenResponse struct {
	Code   int    `json:"code"`                // 响应状态码，0 表示成功
	Msg    string `json:"msg"`                 // 响应消息
	Expire int64  `json:"expire"`              // 令牌有效期（秒）
	Token  string `json:"tenant_access_token"` // 租户访问令牌
}

TokenResponse 飞书 API 令牌响应结构

type Transaction 

type Transaction struct {
	// contains filtered or unexported fields
}

Transaction 实现 sql.driver.Tx 接口的事务结构体 用于兼容 GORM 的事务处理机制

func (*Transaction) Commit 

func (tx *Transaction) Commit() error

Commit 提交事务 实现 sql.driver.Tx 接口

func (*Transaction) ExecContext 

func (tx *Transaction) ExecContext(ctx context.Context, query string, args ...interface{}) (sql.Result, error)

ExecContext 执行语句 实现 gorm.ConnPool 接口

func (*Transaction) PrepareContext 

func (tx *Transaction) PrepareContext(ctx context.Context, query string) (*sql.Stmt, error)

PrepareContext 准备语句 实现 gorm.ConnPool 接口

func (*Transaction) QueryContext 

func (tx *Transaction) QueryContext(ctx context.Context, query string, args ...interface{}) (*sql.Rows, error)

QueryContext 执行查询 实现 gorm.ConnPool 接口

func (*Transaction) QueryRowContext 

func (tx *Transaction) QueryRowContext(ctx context.Context, query string, args ...interface{}) *sql.Row

QueryRowContext 执行单行查询 实现 gorm.ConnPool 接口

func (*Transaction) Rollback 

func (tx *Transaction) Rollback() error

Rollback 回滚事务 实现 sql.driver.Tx 接口

type UpdateRecordRequest 

type UpdateRecordRequest struct {
	Fields map[string]interface{} `json:"fields"` // 要更新的字段值映射
}

UpdateRecordRequest 更新记录的请求结构 用于更新飞书多维表格中的现有记录

func (*UpdateRecordRequest) Validate 

func (req *UpdateRecordRequest) Validate() error

Validate 验证更新记录请求的有效性 返回:

  • error: 如果请求结构无效，返回相应的错误信息

type UpdateRecordResponse 

type UpdateRecordResponse struct {
	Record *Record `json:"record"` // 更新后的记录信息
}

UpdateRecordResponse 更新记录的响应结构 包含更新操作的结果和更新后的记录信息

func (*UpdateRecordResponse) GetRecord 

func (resp *UpdateRecordResponse) GetRecord() *Record

GetRecord 获取更新后的记录 返回:

  • *Record: 更新后的记录，如果操作失败返回 nil

func (*UpdateRecordResponse) IsSuccess 

func (resp *UpdateRecordResponse) IsSuccess() bool

IsSuccess 判断更新记录操作是否成功 返回:

  • bool: 操作是否成功

type User 

type User struct {
	ID     string `json:"id"`      // 用户的唯一标识符
	Name   string `json:"name"`    // 用户的中文名称
	EnName string `json:"en_name"` // 用户的英文名称
	Email  string `json:"email"`   // 用户的邮箱地址
}

User 飞书用户信息结构 表示飞书系统中的用户基本信息

func (*User) GetDisplayName 

func (u *User) GetDisplayName() string

GetDisplayName 获取用户的显示名称 优先返回中文名称，如果中文名称为空则返回英文名称 返回:

  • string: 用户的显示名称

func (*User) Validate 

func (u *User) Validate() error

Validate 验证用户信息的有效性 返回:

  • error: 如果用户信息无效，返回相应的错误信息

Source Files

View all Source files

Directories

Path Synopsis
cmd
basesql command
internal
cli
common
logging
performance
security

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.