appwrite-backend

Appwrite 开发

路由

行动前先加载负责人。未列出的细节 = 阅读负责人信息，切勿推断。

触发条件	负责人
对 Appwrite 执行任何 Agent 操作、设置 MCP 服务或查阅 Appwrite 文档	mcp-servers
生产环境架构／数据／ACL／函数切换	production-migrations；当写入共用一个事务时，另加 transactions
TablesDB 事务或跨服务一致性	transactions；当 ACL 发生变化时，另加 permissions
跨 TablesDB、Auth、Storage、提供商数据或留存的审计证据永久擦除账户／主体数据	destructive-erasure + transactions
批量创建／更新／upsert／删除行、事务限制压力、逐行写入循环	bulk-operations；当原子操作范围跨越多个请求／表时，另加 transactions
按 ID 筛选，且 ID 数量超过已部署的 Query.equal() 值上限	chunked-queries
表／列／索引设计、静态加密、自增、时间戳覆盖、CSV 导入／导出	schema-management
查询结构、select、空间操作、时间辅助工具、怀疑缺少索引	query-optimization
并发修改计数器、数组、字符串或日期字段	atomic-operators
关系建模或遍历	relationships
列表、信息流、无限滚动或大偏移分页	pagination-performance
慢速路径、缓存、增量同步、引导顺序	performance
带宽、执行或存储成本	cost-optimization
会话、MFA、SSR 身份验证、JWT、用户标签、安全设置	authentication
OAuth、魔法链接、电子邮件 OTP、电话、匿名、自定义令牌、电子邮件验证、密码恢复、会话列表／删除、用户偏好设置	auth-methods
ACL 设计、锁定风险、疑似公开泄露	permissions
团队、成员资格或多租户	teams
上传、下载、预览、转换、存储桶配置	storage-files
函数编写、处理程序、运行时、冷启动、环境变量	functions
函数事件、计划任务、幂等性、二进制有效负载、CI/CD	functions-advanced
函数执行 SDK 模型或响应格式解析失败、执行模式、响应检索或执行超时	functions-advanced
Realtime 订阅、频道、在线状态、事件筛选	realtime
推送、电子邮件或 SMS 发送	messaging
向外部系统发送事件	webhooks
头像、姓名首字母、QR、旗帜、favicon	avatars
429、重试、类型化错误、超时、代码为零的传输失败、客户端请求突发、部分同步报告	error-handling；对于启动／引导阶段的请求突发，另加 performance
平台上限或限制错误	limits
国家／地区、货币、语言或地理位置查询	locale
GraphQL 端点	graphql
自托管安装、配置、安全、扩展、SDK 版本固定	self-hosting
自托管备份、恢复、升级、数据丢失事故	self-hosting-ops
健康检查、队列深度、运行时间监控	health

不变量

1. MCP 用于 Agent 操作；官方 SDK 用于应用代码 — Agent 的读取、变更、部署和诊断使用 mcp-servers。缺少 MCP 功能时 → 报告缺口；Agent 操作不得回退到直接使用 SDK、HTTP 或命令行。应用代码使用官方 SDK；只有在缺少 SDK 端点，或需要采用隔离且经过测试的 Client.call 模型解析变通方案时，才可使用原始 Appwrite HTTP（fetch、requests、dio、package:http、curl）。
2. 根据目标和调用方式固定 SDK 版本 — Cloud：使用最新稳定版官方 SDK。自托管：在 self-hosting 中，针对已部署的服务端版本（2.x 或 1.9.x）固定为完全匹配的版本。“兼容 1.9.x”不代表与发行版本完全匹配。更改固定版本前，审查所有中间的破坏性变更，并验证仓库中的实际 SDK 调用在候选版本上可行；仅解析版本并不足够。经过验证的仓库 SDK 固定版本优先于技能中的固定版本。
3. 使用 TablesDB，而非旧版 Databases 服务 — 其 Collections/Documents API 自 1.8.0 起已弃用。DocumentsDB 和 VectorsDB 是独立服务，不属于该旧版 API。
4. 使用 ID.unique() 一次性分配 Appwrite ID — 可重试的创建操作：在首次尝试前调用 ID.unique() → 将返回的 ID 持久化到耐久草稿/意图中 → 每次重试/协调都复用这个完全相同的 ID。重试时重新调用 ID.unique() 会创建第二个资源。业务/自然标识应保存在已索引的列中；绝不能根据名称、时间戳、slug、哈希或自定义生成器派生资源 ID。
5. 明确设置 ACL — 使用服务端 SDK/Console 创建 = 资源 ACL 为空；使用客户端 SDK 创建 = 创建者拥有读取/更新/删除权限。只要 ACL 正确性至关重要，就应显式传入 Permission/Role。
6. 根据已部署目标确定限制 — 页面大小、每个请求的批量行数、事务操作数和 Query.equal() 值数量上限，应以已部署服务端的源码/配置为准，绝不能凭记忆判断。
7. 根据所需结果选择执行模式 — 需要响应数据 → 在 30 秒限制内同步调用 createExecution。异步后台工作 → 有界状态监控 + 与事实来源协调；执行轮询/实时功能无法返回响应正文或标头。长时间运行的结果需要通过授权方式读取持久化结果。只有在协调确认实体仍然存在后，才能报告破坏性操作失败。直接使用同步响应；状态不明确/404 → 重试前先协调。使用 functions-advanced。
8. 验证破坏性操作的范围 — 收缩架构/访问权限需要完整的实时清单 + 精确获批的资源 ID + 备份/恢复证明。缺少字段、分页不完整或访问影响未知时，一律失败关闭。使用 production-migrations。
9. 分阶段执行生产迁移 — 增量扩展 → 按类型进行可恢复的回填 → 兼容性部署 → 收缩/回读 → 激活使用方。数据/架构不完整时，绝不能激活下游代码。使用 production-migrations。
10. 优化前保留写入意图 — 仅更新的工作绝不能通过 upsertRow/upsertRows 执行；预读取、存在性检查或完整负载都不能消除“缺失时创建”的语义。多行应用相同补丁 → 使用 updateRows；每行更新内容不同 → 在已验证的事务预算内使用 createOperations，并在其中设置 action: update，或重新设计。事务压力绝不能成为使用 upsert 的理由。使用 bulk-operations。
11. 编码前批量处理集合写入 — 目标数量可能超过 1，或取决于数据 → 实现前先清点完整变更集和已部署限制。存在兼容的服务端批量方法 → 禁止逐行写入循环。不支持批量操作 → 必须有完整的操作预算 + 对后期失败的原子性证明。完整计划超出上限 → 重新设计或采用可恢复的固定点工作流；绝不能把同一原子不变量拆分到多个已提交的批次中。使用 bulk-operations + transactions。
12. 保留失败的因果关系 — 清理、补偿或回滚失败绝不能取代主要异常。保留两项错误 + 堆栈跟踪 + 执行/事务 ID，报告操作失败，然后核对确切的后置条件。使用 transactions。
13. 协调客户端请求和不确定结果 — 一个按端点/项目范围划分的协调器负责前台、同步、身份验证和重试流量。限制并发；共享 429/传输冷却时间；对代码为 0 的网络故障进行分类；在同一个截止时间内重试读取；任何重复操作前先协调写入/事务；每次失败操作只报告一个事件；部分失败后绝不推进同步检查点。使用 error-handling。

SDK 路由

运行环境	软件包
Web TypeScript/JavaScript/React	appwrite
Node.js/Deno/TypeScript SSR/Functions	node-appwrite
Flutter 客户端	appwrite
Dart 服务器/Functions	dart_appwrite
Python 服务器/Functions	appwrite

• 调用方式：TypeScript 对象参数、Python 关键字参数、Dart 命名参数。仅在与现有代码一致或有明确要求时使用位置参数。
• 客户端 SDK 使用账户会话和用户范围的 API。服务器 SDK 使用 API 密钥。SSR 使用两个客户端：一个可复用的管理客户端用于创建会话，以及一个通过 setSession(...) 设置的按请求创建的会话客户端——绝不可共享。
• Cloud 项目端点 = https://<REGION>.cloud.appwrite.io/v1。
• 在运行时允许的情况下，应在 Function 处理程序预热阶段之外初始化客户端。

资源

文档 https://appwrite.io/docs · API https://appwrite.io/docs/apis/rest · SDK https://github.com/appwrite