Communitygithub.com

sgaabdu4/appwrite-backend

专为AI代理设计的Appwrite BaaS技能。涵盖TablesDB、认证、存储、函数、消息传递和实时功能,支持Dart、Python和TypeScript。

appwrite-backend 是什么?

此技能为AI代理(如Claude Code、Cursor、Codex)提供了完整的Appwrite后端即服务(BaaS)集成指南。它强制要求使用官方SDK(Dart、Flutter、TypeScript、Python),并严格禁止原始HTTP请求,以确保类型安全和版本正确性。技能详细说明了TablesDB API(替代已弃用的Collections API),包括CRUD操作、原子运算符、查询优化和游标分页,以实现高性能。此外,它还涵盖了认证(OAuth、MFA)、存储(文件转换)、实时订阅(类型安全通道)、云函数、事务和权限管理。该指南适用于Appwrite Cloud和自托管1.9.x版本,并提供了清晰的设置说明、反模式列表和成本优化策略,以构建可扩展的、生产就绪的后端。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add sgaabdu4/appwrite-backend

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Appwrite 开发

关键规则

  1. 仅使用官方 SDK 包 — Dart/Flutter/TypeScript/Python 必须使用 sdk-routing。除非SDK缺少某个端点,或者经过隔离测试的 Client.call 可以绕过 SDK 模型解析,否则使用 fetch、requests、dio、package:http、curl 等原始 REST/GraphQL HTTP 均属违规。
  2. 按目标环境锁定 SDK 版本 — 云端:最新稳定版 SDK。自托管 1.9.x:dart_appwrite 25.1.0,Flutter appwrite 25.2.0,node-appwrite 26.2.0,web appwrite 26.1.0,Python appwrite 21.0.0,CLI 22.4.0。
  3. 使用 TablesDB API — Collections API 自 1.8.0 起已弃用。
  4. 对所有唯一 ID 使用 ID.unique() — 行 ID (rowId:)、文件 ID、用户 ID、团队 ID、Webhook ID、消息 ID、订阅者 ID 以及列中的实体 ID。禁止硬编码唯一 ID、自定义生成器、名称、时间戳或作为 ID 的 slug;它们会超出列限制并泄露数据。仅将稳定的自然键用作索引列。
  5. 使用 Query.select() — 关系操作在未显式选择的情况下仅返回 ID。
  6. 使用游标分页 — 偏移量分页在大表上性能会下降。
  7. 使用 Operator 进行计数器操作 — 避免竞态条件。
  8. 创建索引 — 无索引的查询会扫描整个表。
  9. 在处理器外部初始化 — SDK/连接在热启动之间保持持久。
  10. 按领域分组函数 — 每个领域一个函数,而不是每个操作一个。
  11. 事件触发优于轮询 — 一个触发器可替代数千次请求。
  12. 使用显式字符串类型 — string 已弃用;请使用 varchar 或 text/mediumtext/longtext。
  13. 使用 appwrite generate — 从 Schema 生成类型安全的 SDK。
  14. 使用 Channel 辅助函数 — 类型安全的实时订阅,而非原始字符串。
  15. 使用 Realtime 查询 — 服务器端事件过滤,而非客户端。
  16. 异步启动长时间运行的函数 — 针对删除/同步/导入/导出/迁移/生成流程的客户端 createExecution 调用使用异步执行,然后通过有界轮询/实时/获取来调和真相源状态。不要阻塞等待后端完成;仅在调和证明实体/账户仍然存在后报告破坏性故障。

CLI 快速检查(顶部)

每个项目使用仓库本地忽略的 .env.appwrite.local;不要信任全局 CLI 配置。

# .env.appwrite.local (gitignored)
APPWRITE_ENDPOINT=https://<endpoint>/v1
APPWRITE_PROJECT_ID=<project_id>
APPWRITE_API_KEY=standard_...
# 使用 "cloud" 或自托管服务器行。
APPWRITE_SERVER_VERSION=cloud

CLI 版本策略:

  • Appwrite Cloud:最新版 appwrite-cli。
  • 自托管 Appwrite 1.9.x:[email protected]。

在进行 Appwrite CLI 工作之前:

set -a
[ -f .env.appwrite.local ] && . ./.env.appwrite.local
set +a

case "$APPWRITE_SERVER_VERSION" in
  cloud|"")
    npm install -g appwrite-cli@latest
    ;;
  1.9|1.9.*)
    npm install -g [email protected]
    ;;
  *)
    echo "不支持的 APPWRITE_SERVER_VERSION=$APPWRITE_SERVER_VERSION;在继续之前选择一个匹配的 CLI。"
    exit 1
    ;;
esac

appwrite --version
appwrite client \
  --endpoint "$APPWRITE_ENDPOINT" \
  --project-id "$APPWRITE_PROJECT_ID" \
  --key "$APPWRITE_API_KEY"

appwrite client --debug

appwrite client --debug 必须在继续之前显示预期的端点/项目和一个掩码后的密钥。如果缺少,询问端点、项目 ID、API 密钥和服务器版本。

规则:appwrite.config.json = 本地项目配置。appwrite client ... = 全局覆盖(非交互式)。清除覆盖:appwrite client --reset。CLI 辅助标志因版本而异;如果不可用,使用原始 --queries 或解析纯表格输出进行快速状态检查。 详情:appwrite-cli

术语(1.8.0+)

旧新
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

设置

包策略:

  • 云端:最新稳定版官方 SDK。
  • 自托管 1.9.x:使用关键规则 2 中的锁定版本。
  • TypeScript/React 浏览器:appwrite;TypeScript 服务器/SSR/函数:node-appwrite。
  • Python:appwrite;对 SDK 调用优先使用关键字参数。
  • Dart:Flutter/客户端应用使用 appwrite,服务器/函数使用 dart_appwrite;优先使用命名参数。
import 'package:dart_appwrite/dart_appwrite.dart';

final client = Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');

final tablesDB = TablesDB(client);
from appwrite.client import Client
from appwrite.services.tables_db import TablesDB
client = Client()
client.set_endpoint('https://cloud.appwrite.io/v1')
client.set_project('<PROJECT_ID>')
client.set_key('<API_KEY>')
tables_db = TablesDB(client)
import { Client, TablesDB } from 'node-appwrite';
const client = new Client()
    .setEndpoint('https://cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');
const tablesDB = new TablesDB(client);

TablesDB CRUD

// 创建
await tablesDB.createRow(databaseId: 'db', tableId: 'users', rowId: ID.unique(),
    data: {'name': 'Alice'});

// 读取
final rows = await tablesDB.listRows(databaseId: 'db', tableId: 'users',
    queries: [Query.equal('status', 'active'), Query.select(['name', 'email'])]);

// 更新
await tablesDB.updateRow(databaseId: 'db', tableId: 'users', rowId: 'user_123',
    data: {'status': 'inactive'});

// 插入或更新
await tablesDB.upsertRow(databaseId: 'db', tableId: 'settings', rowId: 'prefs',
    data: {'theme': 'dark'});

// 删除
await tablesDB.deleteRow(databaseId: 'db', tableId: 'users', rowId: 'user_123');

使用 SDK 习惯用法:

  • TypeScript 使用对象参数:tablesDB.createRow({ databaseId, tableId, rowId, data })。
  • Python 使用关键字参数:tables_db.create_row(database_id='db', table_id='users', row_id=ID.unique(), data={...})。
  • Dart 使用如上所示的命名参数。

批量操作: bulk-operations.md | 分块 ID 查询: chunked-queries.md


查询参考

比较: equal | notEqual | lessThan | lessThanEqual | greaterThan | greaterThanEqual | between | notBetween 字符串: startsWith | endsWith | contains | search (+ not 变体) 空值: isNull | isNotNull · 逻辑: and([...]) | or([...]) 分页: select | limit | cursorAfter | cursorBefore | orderAsc | orderDesc | orderRandom 时间戳: createdAfter | createdBefore | updatedAfter | updatedBefore 空间: distanceEqual | distanceLessThan | distanceGreaterThan | intersects | overlaps | touches | crosses (+ not 变体)

所有前缀为 Query.。详情:query-optimization.md


运算符(原子更新)

data: {
    'likes': Operator.increment(1),
    'tags': Operator.arrayAppend(['trending']),
    'updatedAt': Operator.dateSetNow(),
}

数值: increment | decrement | multiply | divide 数组: arrayAppend | arrayPrepend | arrayRemove | arrayUnique | arrayIntersect | arrayDiff 其他: toggle | stringConcat | stringReplace | dateAddDays | dateSetNow

详情:atomic-operators.md


列类型

类型最大字符数索引用途
varchar16,383完整(如果大小 < 768)可查询的短字符串
text16,383仅前缀描述、备注
mediumtext4,194,303仅前缀文章
longtext1,073,741,823仅前缀大型文档

string 已弃用。 可查询的字段使用 varchar,非索引字段使用 text。

其他: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon

详情:schema-management.md


性能

规则影响
游标分页比偏移量快 10-100 倍
分页混入(Dart)每个数据源节省约 50 行代码
Query.select()关系查询快 12-18 倍
total: false消除 COUNT 扫描
索引大表快 100 倍
运算符无竞态条件
批量操作N → 1 个请求
Delta 同步仅获取更改的行

详情:performance.md, pagination-performance.md


类型安全 SDK 生成

appwrite generate

从 Schema 生成类型化的辅助函数到 generated/appwrite/。自动完成 + 编译检查。Schema 更改后重新生成。 CLI 流程:login -> init project -> pull -> generate -> push。详情:appwrite-cli


认证

电子邮件/密码、OAuth(50+ 提供商)、电话、魔法链接、匿名、电子邮件 OTP、自定义令牌。MFA:TOTP/电子邮件/电话/恢复码。SSR 会话。用于函数的 JWT。 SSR cookie:a_session_<PROJECT_ID>。管理客户端创建会话。每个请求的会话客户端读取用户上下文。 电子邮件策略可以阻止注册/更新时的免费、别名或一次性电子邮件。

详情:authentication.md | auth-methods.md


存储

上传/下载/预览,支持转换(调整大小、格式转换)。用于可共享 URL 的文件令牌。支持 HEIC、AVIF、WebP。 SDK 处理分块/并行分块上传;不要手动编写上传 HTTP。

详情:storage-files.md


实时

final sub = realtime.subscribe(['tablesdb.db.tables.posts.rows']);
sub.stream.listen((e) => print(e.events));

频道: account | tablesdb.<DB>.tables.<TABLE>.rows | buckets.<BUCKET>.files | presences

频道辅助函数(推荐): Channel 类用于类型安全的订阅,提供 IDE 自动完成:

import { Client, Realtime, Channel, Query } from "appwrite";
const sub = await realtime.subscribe(
    Channel.tablesdb('<DB>').table('<TABLE>').row(),
    response => console.log(response.payload),
    [Query.equal('status', ['active'])]  // 服务器端过滤
);

在支持时使用 Presences API 获取在线/输入/活跃状态;避免为临时状态使用持久化的数据库行和清理定时任务。

详情:realtime.md


函数

在处理器外部初始化 SDK。按领域分组。使用事件触发器,而非轮询。 函数:自托管环境使用规则 2 的 Dart 锁定版本;云端使用最新的 SDK/运行时。

详情:functions.md | functions-advanced.md


事务

final tx = await tablesDB.createTransaction(ttl: 300);
await tablesDB.createRow(..., transactionId: tx.$id);
await tablesDB.updateTransaction(transactionId: tx.$id, commit: true);

详情:transactions.md


关系

await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
    queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);

类型: oneToOne | oneToMany | manyToOne | manyToMany

详情:relationships.md


权限

permissions: [
    Permission.read(Role.any()),
    Permission.update(Role.user(userId)),
    Permission.delete(Role.team('admin')),
    Permission.create(Role.label('premium')),
]

默认: 除非设置了行/文件权限或从表/桶继承,否则全部拒绝。 使用行/文件权限 进行按资源的 ACL。如果所有资源共享相同的规则,则设置表/桶权限,将行/文件权限留空。 write = create + update + delete 避免: 缺少权限 = 无法访问;Role.any() + write/update/delete = 公共修改;对敏感数据的 Permission.read(Role.any()) = 公开泄露。 角色: any() | guests() | users() | user(id) | team(id) | team(id, role) | label(name) 详情:permissions | teams | storage-files


限制

默认页面大小:25 · 批量操作:1000 行 · Query.equal():100 个值 · 嵌套层级:3 层 · 每次请求查询数:100 · 超时:15 秒

错误码

400 错误请求 · 401 未授权 · 403 禁止 · 404 未找到 · 409 冲突 · 429 速率限制(仅客户端 SDK) 捕获 AppwriteException。429 -> 指数退避。

详情:error-handling.md


反模式

错误正确原因
N+1 查询Query.select(['col', 'relation.col'])消除额外的网络往返
读取-修改-写入Operator.increment()竞态条件
大的偏移量Query.cursorAfter(id)O(n) vs O(1)
跳过总数total: false消除 COUNT 扫描
缺少索引为查询的列创建索引查询扫描整个表
在处理器内部初始化 SDK在外部初始化以复用热启动每次调用重复设置
硬编码的秘密环境变量安全风险
轮询实时或事件触发器浪费执行次数
客户端过滤实时查询服务器完成工作
原始频道字符串Channel 辅助函数拼写错误,无自动完成
ColumnStringColumnVarchar 或 ColumnTextstring 已弃用
手动编写类型appwrite generate模式漂移,无自动完成
databases.listDocuments()tablesDB.listRows()已弃用的 API
原始 Appwrite HTTP(fetch、requests、dio、package:http、curl)官方 SDK 包版本漂移、认证错误、丢失类型化 API
自定义/硬编码的唯一 IDID.unique()溢出风险、信息泄漏、冲突
每次同步完全重新获取Query.updatedAfter() + 每个表的时间戳浪费带宽,速度慢
使用 createRow() 循环createRows() 批量操作N 个请求 vs 1 个

成本优化

  1. Query.select() — 减少带宽
  2. 游标分页 + total: false — 最快的查询
  3. 实时优于轮询 — 一个连接 vs 重复调用
  4. 批量操作 — 减少请求数
  5. Delta 同步 — 仅获取更改的数据
  6. 索引 — 消除全表扫描
  7. 按领域分组函数 — 减少冷启动
  8. 使用 async-start 执行长期运行的函数 — 不阻塞客户端
  9. 使用原子运算符而不是读取-修改-写入 — 减少重试次数
  10. 使用 Presences API 获取在线状态 — 避免数据库写入
  11. appwrite generate — 在编译时捕获错误,而不是在运行时
  12. 使用文件令牌而不是公共读/写 — 控制访问
  13. 使用 Webhook 而不是轮询 — 无执行成本

详情:optimization.md

相关技能