Butterbase 快速开始：从声明式 Schema 到自动 REST API 的 5 分钟指南

Butterbase 快速开始从声明式 Schema 到自动 REST API 的 5 分钟指南【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-ossButterbase是一个开源的 BaaSBackend-as-a-Service后端即服务平台用 Postgres 做数据底座内置认证Auth、文件存储、无服务器函数、AI 网关和 MCP Server。这篇文章是一份面向新手的快速开始指南带你用5 分钟体验它最核心的工作流——声明式 Schema定义数据库表平台自动生成自动 REST APIauto-api无需手写一行后端代码。为什么 BaaS 能让后端开发提速传统流程是建表 → 写 CRUD 接口 → 加鉴权 → 加数据隔离 → 部署。每一步都要手写改一个字段要同步改三处代码。Butterbase 的思路是Schema 即 API。你用一份 JSON 描述数据库长什么样平台做三件事把描述翻译成 Postgres DDL 并执行为每张表自动生成完整的 REST 端点增删改查让你用一条策略声明数据隔离行级安全 RLS。 核心收益数据模型是唯一事实来源接口随 Schema 自动更新前端可以直接对着表名开发。第 1 步创建应用并拿到 API Key在平台面板创建一个 App或使用 CLIbutterbase你会得到一个app_id和服务密钥。后续所有请求都挂在/v1/{app_id}/...路径下密钥放请求头里即可。想完整跑起一套自托管环境参考 SETUP.md 与 Makefile需要 Docker、Node 22。第 2 步用声明式 Schema 描述你的表Butterbase 的 Schema 是一门简单的JSON DSL类型定义见 packages/shared/src/schema-dsl.tstables→ 表名columns→ 每列的type、primaryKey、nullable、default、references外键indexes→ 索引定义例如一个待办事项应用只需要这样{ tables: { todos: { columns: { id: { type: uuid, primaryKey: true, default: gen_random_uuid() }, title: { type: text, nullable: false }, done: { type: boolean, default: false }, created_at: { type: timestamptz, default: now() } } } } }把它 POST 到Schema Apply接口即可落地到数据库路由实现在 services/control-api/src/routes/schema.tscurl -X POST https://host/v1/{app_id}/schema/apply \ -H Authorization: Bearer api_key \ -d schema.json平台内部会先做校验Zod 校验 DSL 合法性再对当前数据库结构 vs 你的描述做diff只生成缺失的 DDL 作为迁移执行——重复提交是安全的可以先用dry_run预演。想参考真实项目的写法templates/butterbaseCRM/backend/schema.json 里有一份 29 张表的完整声明式 Schema涵盖外键、JSONB、复合索引等常见用法。第 3 步自动 REST API开箱即用Schema 落库的瞬间每张表自动获得一组 REST 端点实现在 services/control-api/src/routes/auto-api.ts操作方法路径列表查询GET/v1/{app_id}/{table}查询单行GET/v1/{app_id}/{table}/{id}新增POST/v1/{app_id}/{table}更新PATCH/v1/{app_id}/{table}/{id}删除DELETE/v1/{app_id}/{table}/{id}列表接口支持查询过滤如?doneeq.false、排序和分页错误返回也带如何修复的建议对 AI Agent 调用特别友好。也就是说第 2 步做完你的 todos 表已经是一个可用的后端了——前端fetch(/v1/xxx/todos)即可读写。第 4 步加一行 RLS数据立刻隔离自动 API 默认谁登录看到全表多用户场景必须加行级安全Row-Level Security。Butterbase 把 RLS 策略也做成了声明式接口/v1/{app_id}/rls/policies一条策略即可实现每人只能读写自己的数据{ table: todos, name: own_todos_only, expression: owner_id (current_setting(auth.uid)::uuid) }RLS 由数据库引擎强制执行即使绕过应用层也拿不到别人的行。策略 DSL 与实现细节可在数据面迁移 db/data-plane/005_rls_role_based.sql 中查看。实战验证5 分钟后你拥有的是什么完成上面四步一个带自动 REST API 和权限隔离的后端就跑起来了。如果想直接克隆一个生产级应用感受完整形态官方提供了 templates/butterbaseCRM29 张表、55 函数、全表 RLS克隆时会完整复刻 Schema、RLS 策略、函数与 AI 配置新应用拥有独立数据库与 API Key。更多示例见 Examples/ 与 templates/README.md。常见问题FAQQ重复提交 Schema 会覆盖已有数据吗A不会。Schema Apply 是增量 diff只补建缺失的表和列已存在的表结构保持不变。Q自动 REST API 会绕过 RLS 吗A不会。所有 auto-api 请求都运行在受 RLS 约束的角色下行级隔离由 Postgres 强制执行。Q能加自定义复杂逻辑吗A可以。auto-api 负责标准 CRUD复杂业务交给 TypeScript 无服务器函数packages/cli/src/commands/functions.tsAI 调用则走内置 AI 网关。小结声明式 SchemaJSON 描述表结构平台自动 diff 并生成迁移自动 REST API每张表免费获得标准 CRUD 端点RLS 一行隔离策略声明式管理数据库级强制下一步把前端指向上文端点或用 MCP Server 让 AI Agent 直接操作你的后端——完整的开源 BaaS 能力Postgres · Auth · Storage · Functions · AI Gateway · MCP已在 README.md 中列出。【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考