# go-aitable **Repository Path**: stonehill-2345/go-aitable ## Basic Information - **Project Name**: go-aitable - **Description**: 基于 Go 泛型（1.22+）的统一A1 表格产品 SDK，支持企业微信智能表、飞书多维表格和钉钉 Al 表格，实现“一处定义，多平台适配”的设计理念。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-12-25 - **Last Updated**: 2025-12-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # go-aitable [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Go Version](https://img.shields.io/badge/Go-1.22+-blue.svg)](https://golang.org/doc/go1.22) [中文](./README.md) | [English](./README_en.md) 基于 Go 泛型（1.22+）的统一 AI 表格产品 SDK，支持企微智能表、飞书多维表格和钉钉 AI 表格，实现"一处定义，多平台适配"的设计理念。 ## 功能特性 - **泛型驱动设计**：所有核心接口均基于 Go 泛型（1.22+）构建 - **多平台支持**： - 企微智能表（已实现基础操作） - 飞书多维表格（Todo...） - 钉钉 AI 表格（Todo...） - **统一 CRUD 操作**：所有业务模型共享同一个泛型 RecordService - **直接模型映射**：基于标签的业务模型字段映射 - **可扩展设计**：支持自定义缓存、日志、HTTP 客户端等 - **自动平台注册**：平台通过init函数自动注册 - **基于标签的映射**：使用结构体标签进行灵活的字段映射 - **测试完善**：核心功能的全面测试覆盖 ## 项目结构 ``` go-aitable/ ├── aitable.go # 主 SDK 入口 ├── core/ # 核心接口和类型定义 │ ├── api/ # 平台适配器和注册表接口 │ ├── option/ # 配置选项 │ ├── error.go # 统一错误定义 │ ├── platform.go # 平台常量和类型 │ └── types.go # 核心类型定义 ├── platforms/ # 平台特定实现 │ ├── common/ # 平台通用工具 │ ├── dingtalk/ # 钉钉 AI 表格实现 │ ├── feishu/ # 飞书多维表格实现 │ └── wecom/ # 企微智能表实现 ├── internal/ # 内部工具 │ ├── cache/ # 缓存实现 │ ├── errors/ # 错误定义 │ ├── logger/ # 日志工具 │ └── utils/ # 通用工具 ├── examples/ # 使用示例 ├── test/ # 测试文件 ├── README.md # 中文文档 ├── README_en.md # 英文文档 ├── .golangci.yml # Lint 配置 ├── go.mod # 模块定义 └── go.sum # 依赖校验 ``` ## 架构设计 ### 核心设计原则 - **面向接口**：所有组件通过接口通信 - **适配器模式**：平台特定实现封装在适配器中 - **注册表模式**：通过中央注册表管理平台适配器 - **泛型驱动**：核心服务使用泛型确保类型安全和灵活性 ### 组件关系 ```mermaid flowchart TD A[用户应用程序] --> B[aitable.Client] B --> C[core/api.Client] C --> D[core/api.PlatformRegistry] D --> E[core/api.PlatformAdapter] E --> F[platforms/wecom/adapter.WeComAdapter] E --> G[platforms/feishu/adapter.FeiShuAdapter] E --> H[platforms/dingtalk/adapter.DingTalkAdapter] F --> I[platforms/wecom/Table Adapter] G --> J[platforms/feishu/Table Adapter] H --> K[platforms/dingtalk/Table Adapter] I --> L[platforms/wecom/Record Adapter] J --> M[platforms/feishu/Record Adapter] K --> N[platforms/dingtalk/Record Adapter] ``` ### 关键组件 - **核心客户端**：主入口点，处理客户端创建和配置 - **平台注册表**：管理平台适配器，支持通过init函数动态注册 - **平台适配器**：封装平台特定逻辑，为每个平台实现核心接口 - **服务适配器**：每个平台的表格和记录服务实现 - **通用映射器**：基于标签的业务模型字段映射工具 - **平台客户端**：每个平台的特定客户端实现 - **平台服务**：平台特定的表格和记录操作 ## 快速开始 ### 1、安装 SDK ```sh go get github.com/stonehill-2345/go-aitable ``` ### 2. 定义业务模型 ```go import "time" // Task 是表示 AI 表格中任务的业务模型 type Task struct { RecordID string `json:"record_id"` // 智能表行ID UserID float64 `json:"uid" name:"用户ID" type:"number" sort:"idx1_desc_true"` // 用户ID UserName string `json:"user_name" name:"用户名" type:"text"` // 用户名 AvatarURL []core.ImageValue `json:"avatar_url" name:"头像" type:"image"` // 用户头像 Gender string `json:"gender" name:"性别" type:"option"` // 性别, 选项: 男,女,未知 Age float64 `json:"age" name:"年龄" type:"number"` // 年龄 Hobby []string `json:"hobby" name:"爱好" type:"option"` // 爱好, 选项: 篮球,足球,跑步 DataTime time.Time `json:"data_time" name:"录入日期" type:"date" sort:"idx2_desc_true"` // 日期 Remark string `json:"remark" name:"备注" type:"text"` // 备注 } // 实现 BusinessModel 约束（所有业务模型必须实现） func (t *Task) GetRecordID() string { return t.RecordID } func (t *Task) SetRecordID(id string) { t.RecordID = id } func (t *Task) IsBusinessModel() {} // 仅用于约束的空方法 ``` ### 3. 创建客户端并使用 RecordService ```go import ( "context" "fmt" "github.com/stonehill-2345/go-aitable" "github.com/stonehill-2345/go-aitable/core/option" "github.com/stonehill-2345/go-aitable/core/api" ) func main() { ctx := context.Background() // 创建企微客户端 client, err := aitable.NewClient( ctx, option.WithPlatform(option.PlatformWeCom), option.WithWeComAuth("your-corp-id", "your-app-secret"), ) if err != nil { panic(err) } // 使用 GetRecordService 获取 Task 模型的泛型 RecordService taskService, err := aitable.GetRecordService[*Task](client) if err != nil { panic(err) } // 创建新任务 newTask := &Task{ UserID: 1001, UserName: "zhangsan", Gender: "男", Hobby: []string{"篮球", "足球"}, Age: 30, AvatarURL: []core.ImageValue{{URL: "https://lf-flow-web-cdn.doubao.com/obj/flow-doubao/doubao/chat/static/image/logo-icon-white-bg.72df0b1a.png"}}, DataTime: time.Now(), Remark: "这个用户很有才华2", } // 创建记录请求 createReq := &api.CreateRecordsRequest[*Task]{ DocID: "your-doc-id", SheetID: "your-sheet-id", Records: []*Task{newTask}, } // 添加记录 createResp, err := taskService.CreateRecords(ctx, createReq) if err != nil { panic(err) } fmt.Printf("创建的记录 ID: %v\n", createResp.RecordIDs) // 更新记录 newTask.RecordID = createResp.RecordIDs[0] newTask.UserName = "更新后的用户名" newTask.Age = 31 updateReq := &api.UpdateRecordsRequest[*Task]{ DocID: "your-doc-id", SheetID: "your-sheet-id", Records: []*Task{newTask}, } err = taskService.UpdateRecords(ctx, updateReq) if err != nil { panic(err) } fmt.Println("更新记录成功") // 删除记录 deleteReq := &api.DeleteRecordsRequest{ DocID: "your-doc-id", SheetID: "your-sheet-id", RecordIDs: []string{newTask.RecordID}, } err = taskService.DeleteRecords(ctx, deleteReq) if err != nil { panic(err) } fmt.Println("删除记录成功") // 查询记录 queryReq := &api.GetRecordsRequest{ DocID: "your-doc-id", SheetID: "your-sheet-id", Options: &option.RecordOptions{ PageSize: 10, PageNum: 1, }, } queryResp, err := taskService.GetRecords(ctx, queryReq) if err != nil { panic(err) } fmt.Printf("查询到 %d 条记录，共 %d 条\n", len(queryResp.Records), queryResp.Total) for _, task := range queryResp.Records { fmt.Printf("任务：ID=%s, 用户名=%s, 年龄=%f\n", task.RecordID, task.UserName, task.Age) } } ``` ## 业务模型标签 SDK 使用结构体标签将业务模型字段映射到 AI 表格列。以下是每个标签的详细说明： | 标签名称 | 描述 | 示例 | 是否必填 | | -------- | -------------------------------------------------------- | ----------------------- | -------- | | `name` | 将结构体字段映射到 AI 表格列名 | `name:"任务名称"` | 是 | | `type` | 定义字段数据类型（text, number, date, option, image 等） | `type:"text"` | 是 | | `sort` | 定义字段的排序行为 | `sort:"idx1_desc_true"` | 否 | | `sync` | 控制字段是否应该在模型和表格之间同步 | `sync:"true"` | 否 | ### 支持的字段类型 | 类型 | 描述 | 平台支持 | | -------- | ------------------------ | -------- | | `text` | 文本字段 | 所有平台 | | `number` | 数字字段（float） | 所有平台 | | `date` | 日期和时间字段 | 所有平台 | | `option` | 单选/多选字段 | 所有平台 | | `image` | 图片字段（URL 或二进制） | 所有平台 | | `url` | URL 字段（支持多个） | 所有平台 | ## 支持的平台 ### 企微智能表 智能文档操作效果如下： [【企微文档】【示例】企微智能表](https://doc.weixin.qq.com/smartsheet/s3_AIwAIxRYAP0CN54F9pnZrQf0r2qZp_a?scode=AGEAtQdGAEYgp1nli0AbQAogZ1AKc&tab=q979lj) ![企微智能表操作效果](./images/企微智能表示例.png) ### 飞书多维表格 ```go // Todo... ``` ### 钉钉 AI 表格 ```go // Todo... ``` ## 配置选项 SDK 提供了各种配置选项来自定义其行为。以下是每个选项的详细说明： | 选项 | 描述 | 默认值 | 必填 | | ------------------- | ---------------------------------------- | -------------- | ---- | | `WithPlatform` | 设置平台类型（企微、飞书、钉钉） | - | 是 | | `WithWeComAuth` | 设置企微认证凭证（CorpID, AppSecret） | - | 企微 | | `WithFeiShuAuth` | 设置飞书认证凭证（AppID, AppSecret） | - | 飞书 | | `WithDingTalkAuth` | 设置钉钉认证凭证（AppKey, AppSecret） | - | 钉钉 | | `WithDebug` | 启用调试模式，提供详细日志 | false | 否 | | `WithTimeout` | 设置 API 请求的 HTTP 超时时间 | 15s | 否 | | `WithHTTPClient` | 设置自定义 HTTP 客户端用于 API 请求 | 默认 Go 客户端 | 否 | | `WithLogger` | 设置自定义日志实现 | 默认日志 | 否 | | `WithLoggerLevel` | 设置日志级别（debug, info, warn, error） | info | 否 | | `WithTokenCache` | 设置自定义令牌缓存实现 | 内存缓存 | 否 | | `WithRecordOptions` | 为所有记录操作设置默认记录选项 | 默认选项 | 否 | 记录选项允许您自定义记录操作： | 选项 | 描述 | 默认值 | | ------------------ | ------------------------------ | -------- | | `PageSize` | 查询结果每页的记录数量 | 100 | | `PageNum` | 查询结果的页码 | 1 | | `ZeroUpdateFields` | 即使值为零也需要更新的字段列表 | - | | `NeedTotal` | 是否返回总记录数 | true | | `Fields` | 结果中包含的特定字段 | 所有字段 | ## 测试 ### 环境变量 测试文件使用环境变量进行配置。在项目根目录创建 `.env` 文件，内容如下： ``` # 企微配置 WECOM_CORP_ID=your_wecom_corp_id WECOM_SECRET_KEY=your_wecom_secret_key WECOM_APP_SECRET=your_wecom_app_secret # 文档和表格配置 WECOM_DOC_ID=your_wecom_doc_id WECOM_SHEET_ID=your_wecom_sheet_id WECOM_TEST_RECORD_ID=your_wecom_test_record_id # Redis配置 REDIS_ADDR=localhost:6379 REDIS_PASSWORD=your_redis_password ``` 项目提供了 `.env.example` 示例文件供参考。 ## 最低 Go 版本 需要 Go 1.22+ 以支持完整泛型功能 ## 路线图 - [x] 企微智能表泛型支持（基本功能） - [ ] 飞书多维表格实现 - [ ] 钉钉 AI 表格实现 - [ ] 高级表格操作（人员操作，AI结合功能等） - [ ] 性能优化和基准测试 ## 许可证 APACHE 2.0 许可证 ## 贡献 欢迎贡献！请随时提交 Pull Request。 ## 联系方式 如果您有任何问题或建议，请在 GitHub 上打开一个 issue。