Appwrite 开发
关键规则
- 仅使用官方 SDK 包 — Dart/Flutter/TypeScript/Python 必须使用 sdk-routing。除非SDK缺少某个端点,或者经过隔离测试的
Client.call可以绕过 SDK 模型解析,否则使用fetch、requests、dio、package:http、curl等原始 REST/GraphQL HTTP 均属违规。 - 按目标环境锁定 SDK 版本 — 云端:最新稳定版 SDK。自托管
1.9.x:dart_appwrite25.1.0,Flutterappwrite25.2.0,node-appwrite26.2.0,webappwrite26.1.0,Pythonappwrite21.0.0,CLI 22.4.0。 - 使用 TablesDB API — Collections API 自 1.8.0 起已弃用。
- 对所有唯一 ID 使用
ID.unique()— 行 ID (rowId:)、文件 ID、用户 ID、团队 ID、Webhook ID、消息 ID、订阅者 ID 以及列中的实体 ID。禁止硬编码唯一 ID、自定义生成器、名称、时间戳或作为 ID 的 slug;它们会超出列限制并泄露数据。仅将稳定的自然键用作索引列。 - 使用
Query.select()— 关系操作在未显式选择的情况下仅返回 ID。 - 使用游标分页 — 偏移量分页在大表上性能会下降。
- 使用 Operator 进行计数器操作 — 避免竞态条件。
- 创建索引 — 无索引的查询会扫描整个表。
- 在处理器外部初始化 — SDK/连接在热启动之间保持持久。
- 按领域分组函数 — 每个领域一个函数,而不是每个操作一个。
- 事件触发优于轮询 — 一个触发器可替代数千次请求。
- 使用显式字符串类型 —
string已弃用;请使用varchar或text/mediumtext/longtext。 - 使用
appwrite generate— 从 Schema 生成类型安全的 SDK。 - 使用 Channel 辅助函数 — 类型安全的实时订阅,而非原始字符串。
- 使用 Realtime 查询 — 服务器端事件过滤,而非客户端。
- 异步启动长时间运行的函数 — 针对删除/同步/导入/导出/迁移/生成流程的客户端
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+)
| 旧 | 新 |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
设置
包策略:
- 云端:最新稳定版官方 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
列类型
| 类型 | 最大字符数 | 索引 | 用途 |
|---|---|---|---|
varchar | 16,383 | 完整(如果大小 < 768) | 可查询的短字符串 |
text | 16,383 | 仅前缀 | 描述、备注 |
mediumtext | 4,194,303 | 仅前缀 | 文章 |
longtext | 1,073,741,823 | 仅前缀 | 大型文档 |
string已弃用。 可查询的字段使用varchar,非索引字段使用text。
其他: integer | float | boolean | datetime | email | url | ip | enum | relationship | point | line | polygon
性能
| 规则 | 影响 |
|---|---|
| 游标分页 | 比偏移量快 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。
实时
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);
关系
await tablesDB.listRows(databaseId: 'db', tableId: 'posts',
queries: [Query.equal('author.country', 'US'), Query.select(['title', 'author.name'])]);
类型: oneToOne | oneToMany | manyToOne | manyToMany
权限
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 -> 指数退避。
反模式
| 错误 | 正确 | 原因 |
|---|---|---|
| N+1 查询 | Query.select(['col', 'relation.col']) | 消除额外的网络往返 |
| 读取-修改-写入 | Operator.increment() | 竞态条件 |
| 大的偏移量 | Query.cursorAfter(id) | O(n) vs O(1) |
| 跳过总数 | total: false | 消除 COUNT 扫描 |
| 缺少索引 | 为查询的列创建索引 | 查询扫描整个表 |
| 在处理器内部初始化 SDK | 在外部初始化以复用热启动 | 每次调用重复设置 |
| 硬编码的秘密 | 环境变量 | 安全风险 |
| 轮询 | 实时或事件触发器 | 浪费执行次数 |
| 客户端过滤 | 实时查询 | 服务器完成工作 |
| 原始频道字符串 | Channel 辅助函数 | 拼写错误,无自动完成 |
ColumnString | ColumnVarchar 或 ColumnText | string 已弃用 |
| 手动编写类型 | appwrite generate | 模式漂移,无自动完成 |
databases.listDocuments() | tablesDB.listRows() | 已弃用的 API |
原始 Appwrite HTTP(fetch、requests、dio、package:http、curl) | 官方 SDK 包 | 版本漂移、认证错误、丢失类型化 API |
| 自定义/硬编码的唯一 ID | ID.unique() | 溢出风险、信息泄漏、冲突 |
| 每次同步完全重新获取 | Query.updatedAfter() + 每个表的时间戳 | 浪费带宽,速度慢 |
使用 createRow() 循环 | createRows() 批量操作 | N 个请求 vs 1 个 |
成本优化
Query.select()— 减少带宽- 游标分页 +
total: false— 最快的查询 - 实时优于轮询 — 一个连接 vs 重复调用
- 批量操作 — 减少请求数
- Delta 同步 — 仅获取更改的数据
- 索引 — 消除全表扫描
- 按领域分组函数 — 减少冷启动
- 使用
async-start执行长期运行的函数 — 不阻塞客户端 - 使用原子运算符而不是读取-修改-写入 — 减少重试次数
- 使用 Presences API 获取在线状态 — 避免数据库写入
appwrite generate— 在编译时捕获错误,而不是在运行时- 使用文件令牌而不是公共读/写 — 控制访问
- 使用 Webhook 而不是轮询 — 无执行成本