Appwrite 開發
關鍵規則
- 僅使用官方 SDK 套件 — Dart/Flutter/TypeScript/Python 必須使用 sdk-routing。除非 SDK 缺少某端點,或使用隔離且經過測試的
Client.call來繞過 SDK 模型解析,否則使用fetch、requests、dio、package:http、curl等原始 REST/GraphQL HTTP 皆屬違規。 - 按目標環境鎖定 SDK 版本 — Cloud:使用最新的穩定版 SDK。自託管
1.9.x:dart_appwrite25.1.0、Flutterappwrite25.2.0、node-appwrite26.2.0、網頁appwrite26.1.0、Pythonappwrite21.0.0、CLI 22.4.0。 - 使用 TablesDB API — 已於 1.8.0 棄用 Collections API。
- 所有唯一 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 Helper — 類型安全的 Realtime 訂閱,而非原始字串。
- 使用 Realtime 查詢 — 伺服器端事件過濾,而非客戶端過濾。
- 非同步啟動長時間執行的函式 — 客戶端對刪除/同步/匯入/匯出/遷移/生成流程的
createExecution呼叫應使用非同步執行,然後透過有限制的輪詢/Realtime/fetch 來調解資料來源狀態。不要阻塞等待後端完成;只有在調解證明實體/帳戶仍然存在後,才報告破壞性失敗。
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 及經過遮罩的密鑰。如果缺少,請詢問端點、專案 ID、API 金鑰及伺服器版本。
規則:appwrite.config.json = 本地專案設定。appwrite client ... = 全域覆蓋(非互動式)。清除覆蓋:appwrite client --reset。CLI helper flags 因版本而異;若不可用,請使用原始 --queries 或解析純文字表格輸出以進行快速狀態檢查。
詳細資訊:appwrite-cli
詞彙表(1.8.0+)
| 舊名稱 | 新名稱 |
|---|---|
| Collections | Tables |
| Documents | Rows |
| Attributes | Columns |
| Databases | TablesDB |
設定
套件政策:
- Cloud:最新的穩定版官方 SDK。
- 自託管
1.9.x:使用關鍵規則 2 的固定版本。 - TypeScript/React 瀏覽器:
appwrite;TypeScript 伺服器/SSR/Functions:node-appwrite。 - Python:
appwrite;SDK 呼叫偏好使用關鍵字引數。 - Dart:Flutter/客戶端應用程式使用
appwrite,伺服器/Functions 使用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'});
// Upsert(存在則更新,否則插入)
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
資料行類型
| 類型 | 最大字元數 | 索引支援 | 用途 |
|---|---|---|---|
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
詳細資訊:schema-management.md
效能
| 規則 | 影響 |
|---|---|
| 游標分頁 | 比偏移分頁快 10-100 倍 |
| 分頁 mixin(Dart) | 每個資料來源節省約 50 行程式碼 |
Query.select() | 關聯查詢快 12-18 倍 |
total: false | 消除 COUNT 掃描 |
| 索引 | 大型資料表快 100 倍 |
| 運算子 | 無競爭條件 |
| 大量操作 | N → 1 個請求 |
| 增量同步 | 僅擷取變更的資料行 |
詳細資訊:performance.md、pagination-performance.md
類型安全的 SDK 生成
appwrite generate
從 Schema 生成類型化的 helper 到 generated/appwrite/。自動完成 + 編譯檢查。Schema 變更後重新生成。
CLI 流程:login -> init project -> pull -> generate -> push。詳細資訊:appwrite-cli
身份驗證
電子郵件/密碼、OAuth(超過 50 家提供商)、電話、魔法連結、匿名、電子郵件 OTP、自訂令牌。MFA:TOTP/電子郵件/電話/恢復碼。SSR Session。用於 Functions 的 JWT。
SSR Cookie:a_session_<PROJECT_ID>。Admin 客戶端建立 Session。每個請求的 Session 客戶端讀取使用者上下文。
電子郵件政策可以在註冊/更新時封鎖免費、別名或一次性電子郵件。
詳細資訊:authentication.md | auth-methods.md
儲存
上傳/下載/預覽(含轉換功能,如調整大小、格式轉換)。檔案令牌用於可分享的 URL。支援 HEIC、AVIF、WebP。 SDK 處理分塊/並行分塊上傳;請勿手動實作上傳 HTTP。
詳細資訊:storage-files.md
Realtime
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 Helper(建議使用): 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 來處理線上/打字中/活躍狀態;避免為短暫狀態建立持久性 DB 資料行及清理 cron 作業。
詳細資訊:realtime.md
Functions
在處理器外部初始化 SDK。按領域分組。使用事件觸發,而非輪詢。 Functions:自託管使用規則 2 的 Dart 固定版本;Cloud 使用最新的 SDK/Runtime。
詳細資訊: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) 對比 O(1) |
| 略過總數 | total: false | 消除 COUNT 掃描 |
| 缺少索引 | 為查詢的資料行建立索引 | 查詢掃描整個資料表 |
| 在處理器內部初始化 SDK | 在外部初始化以實現溫暖重用 | 每次呼叫都重複設定 |
| 硬編碼密碼 | 環境變數 | 安全風險 |
| 輪詢 | Realtime 或事件觸發器 | 浪費執行 |
| 客戶端過濾 | Realtime 查詢 | 伺服器進行工作 |
| 原始頻道字串 | Channel Helper | 拼寫錯誤,無自動完成 |
ColumnString | ColumnVarchar 或 ColumnText | string 已棄用 |
| 手寫類型 | appwrite generate | Schema 漂移,無自動完成 |
databases.listDocuments() | tablesDB.listRows() | 已棄用的 API |
原始 Appwrite HTTP(fetch、requests、dio、package:http、curl) | 官方 SDK 套件 | 版本漂移、驗證錯誤、遺失類型化 API |
| 自訂/硬編碼的唯一 ID | ID.unique() | 溢出風險、資訊洩漏、衝突 |
| 每次同步都完整重新擷取 | Query.updatedAfter() + 每個資料表的時間戳 | 浪費頻寬,速度慢 |
用迴圈執行 createRow() | 使用 createRows() 進行大量操作 | N 個請求對比 1 個 |
成本最佳化
Query.select()— 減少頻寬- 游標分頁 +
total: false— 最快的查詢 - Realtime 優於輪詢 — 一個連線對比重複呼叫
- 大量操作 — 減少請求次數