Communitygithub.com

sgaabdu4/appwrite-backend

適用於 AI Agent 的 Appwrite BaaS 技能。涵蓋 TablesDB、Auth、Storage、Functions、Messaging 和 Realtime,支援 Dart、Python 和 TypeScript。

appwrite-backend 是什麼?

此技能為 AI Agent(如 Cursor、Claude Code 等)提供 Appwrite 後端即服務整合。它強制使用官方 SDK,不論是 Dart、Flutter、TypeScript、Node.js 還是 Python,避免直接使用原始 REST/GraphQL HTTP 請求。核心規則包括使用 TablesDB API(而非已棄用的 Collections API)、使用 `ID.unique()` 自動生成所有唯一 ID、使用 `Query.select()` 優化關聯查詢、以及使用游標分頁以實現大規模資料集的高效處理。該技能涵蓋 CRUD 操作、原子更新、Realtime 訂閱、Storage、Functions、Authentication、交易和權限管理。它還針對不同部署方式(Appwrite Cloud 或自託管 1.9.x)提供 SDK 版本固定指南,並提供 CLI 設置說明。此外,技能文件中包含效能優化技巧、常見反模式、連結到詳細參考資料的指南,以及基於 Schema 的類型安全 SDK 生成功能。

相容平台~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 版本 — Cloud:使用最新的穩定版 SDK。自託管 1.9.x:dart_appwrite 25.1.0、Flutter appwrite 25.2.0、node-appwrite 26.2.0、網頁 appwrite 26.1.0、Python appwrite 21.0.0、CLI 22.4.0。
  3. 使用 TablesDB API — 已於 1.8.0 棄用 Collections API。
  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 Helper — 類型安全的 Realtime 訂閱,而非原始字串。
  15. 使用 Realtime 查詢 — 伺服器端事件過濾,而非客戶端過濾。
  16. 非同步啟動長時間執行的函式 — 客戶端對刪除/同步/匯入/匯出/遷移/生成流程的 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+)

舊名稱新名稱
CollectionsTables
DocumentsRows
AttributesColumns
DatabasesTablesDB

設定

套件政策:

  • 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


資料行類型

類型最大字元數索引支援用途
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 倍
分頁 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拼寫錯誤,無自動完成
ColumnStringColumnVarchar 或 ColumnTextstring 已棄用
手寫類型appwrite generateSchema 漂移,無自動完成
databases.listDocuments()tablesDB.listRows()已棄用的 API
原始 Appwrite HTTP(fetch、requests、dio、package:http、curl)官方 SDK 套件版本漂移、驗證錯誤、遺失類型化 API
自訂/硬編碼的唯一 IDID.unique()溢出風險、資訊洩漏、衝突
每次同步都完整重新擷取Query.updatedAfter() + 每個資料表的時間戳浪費頻寬,速度慢
用迴圈執行 createRow()使用 createRows() 進行大量操作N 個請求對比 1 個

成本最佳化

  1. Query.select() — 減少頻寬
  2. 游標分頁 + total: false — 最快的查詢
  3. Realtime 優於輪詢 — 一個連線對比重複呼叫
  4. 大量操作 — 減少請求次數

相關技能