AppBase 云控制台
浏览全部文档 · 32/37
已支持已进入 main

错误响应、幂等与安全重试

SDK、REST、GraphQL 与错误处理

版本验证信息发布状态与验证 Commit
发布状态
已进入 main
后端验证 Commit
3c7e888f98417f1a6114a42ac1f97bc40cf16cac

功能简介

客户端应把 HTTP status、公开 type/code 和结构化字段作为程序判断依据，不依赖 message 字符串。认证失败、权限不足、不可见资源、参数错误、状态冲突和基础设施故障必须保持可区分；只有明确的安全查询边界才能把不可见资源归一化为 not found。

当前支持范围

  • REST API（SUPPORTED）：核心服务通过版本化 REST API 暴露，每个接口单独声明认证类型、Scope 与响应模型。
  • 认证、Scope 与资源权限（SUPPORTED）：用 Session、JWT、API Key、细粒度 Scope、Role 与资源级 Permission 共同保护项目控制面和数据面。

适用场景

  • 为 SDK/REST 调用建立稳定错误分支。
  • 设计创建、事务和异步任务的幂等重试。
  • 避免开发环境错误诊断泄漏 Cookie、Token 或请求体。

前置条件

  • 记录 request ID、status 与公开 code，不记录凭据或原始敏感 body。
  • 为每个写操作确认是否存在 Idempotency-Key 或业务唯一键。
  • 区分业务拒绝与 Redis、数据库、网络、配置故障。

Console 操作路径

Console 会显示经过公开映射的错误。开发环境可保留 file、line、class、type、function 等安全 Trace 定位字段，但不会返回 frame args、object、request、headers、cookies 或 body；生产环境不新增 Trace。

SDK 示例

SDK · TypeScript
import { AppBaseException } from 'appbase-web-sdk';

try {
  await operation();
} catch (error) {
  if (error instanceof AppBaseException) {
    console.error({
      code: error.code,
      type: error.type
      // 不记录 error.response、Cookie、Token 或原始请求体。
    });
  }
  throw error;
}

REST 示例

REST · Bash
curl -i 'https://<APPBASE_HOST>/v1/account' \
  -H 'X-Appwrite-Project: <PROJECT_ID>' \
  -H 'X-Appwrite-JWT: <USER_JWT>'

权限模型

401 表示没有可用身份或身份类型不被接受；403 表示身份已识别但 Role/Scope/Permission 不足；安全 404 可能同时代表不存在与不可见。5xx/503 必须作为服务故障传播。

常见错误

现象处理建议
400修正参数或请求冲突；不要无条件重试。
401刷新或重新建立身份；不要把同一失效凭据循环重试。
403调整授权设计或请求最小 Scope，不通过关闭授权绕过。
404按公开 not found 处理，不向用户泄漏资源存在性。
409检查幂等键、版本或状态机。
429/5xx只对幂等请求指数退避，并设置总重试预算。

当前限制

  • 公开 message 可能随版本本地化或改进，不是稳定分支条件。
  • 不要 catch 所有异常后统一返回 404。
  • 不要仅依赖 SensitiveParameter 或 zend.exception_ignore_args=1 作为 Trace 安全防线。

Appwrite 兼容说明

错误类型和权限概念保持兼容；开发 Trace 的结构化安全投影来自 AppBase 安全修复。

AppBase 增强说明

AppBase 将开发诊断与凭据安全分离：保留定位结构，删除所有运行时值，并保持 production 响应不变。

发布状态和验证 Commit

Target main 已核验。验证 Commit：3c7e888f98417f1a6114a42ac1f97bc40cf16cac。

权威来源文件列表

  • backend-candidate:app/controllers/api/
  • backend-candidate:app/controllers/api/projects.php
  • backend-candidate:app/controllers/general.php
  • backend-candidate:app/http.php
  • backend-candidate:docs/references/
  • backend-candidate:src/Appwrite/Utopia/Response/ErrorTrace.php
  • backend-candidate:src/Appwrite/Platform/Modules/*/Http/
  • backend-candidate:tests/e2e/Services/Databases/DatabasesBase.php
  • backend-candidate:tests/e2e/Services/Storage/StorageCustomClientTest.php

Appwrite taxonomy 仅作信息架构参考：https://appwrite.io/docs/advanced/security、https://appwrite.io/docs/apis/rest。上游页面不是 AppBase 实现证据。

继续阅读