Back to Details

pocketbase-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

PocketBase Best Practices

PocketBase 开发最佳实践

42 rules across 8 categories for PocketBase v0.36+, prioritized by impact.
针对PocketBase v0.36+版本，按影响优先级划分的8个类别共42条规则。

When to Apply

适用场景

  • Designing collections and schema structures
  • Implementing API rules for access control
  • Setting up authentication (password, OAuth2, MFA)
  • Using the PocketBase JavaScript SDK
  • Optimizing queries with filtering, sorting, and expansion
  • Implementing realtime subscriptions
  • Handling file uploads and storage
  • Deploying PocketBase to production
  • 设计集合和模式结构
  • 实现用于访问控制的API规则
  • 设置身份验证（密码、OAuth2、MFA）
  • 使用PocketBase JavaScript SDK
  • 通过过滤、排序和扩展优化查询
  • 实现实时订阅
  • 处理文件上传和存储
  • 将PocketBase部署到生产环境

Categories by Priority

按优先级划分的类别

PriorityCategoryImpactRules
1Collection DesignCRITICALcoll-field-types, coll-auth-vs-base, coll-relations, coll-indexes, coll-view-collections, coll-geopoint
2API Rules & SecurityCRITICALrules-basics, rules-filter-syntax, rules-request-context, rules-cross-collection, rules-locked-vs-open
3AuthenticationCRITICALauth-password, auth-oauth2, auth-token-management, auth-mfa, auth-impersonation
4SDK UsageHIGHsdk-initialization, sdk-auth-store, sdk-error-handling, sdk-auto-cancellation, sdk-filter-binding, sdk-field-modifiers, sdk-send-hooks
5Query PerformanceHIGHquery-pagination, query-expand, query-field-selection, query-batch-operations, query-n-plus-one, query-first-item, query-back-relations
6RealtimeMEDIUMrealtime-subscribe, realtime-events, realtime-auth, realtime-reconnection
7File HandlingMEDIUMfile-upload, file-serving, file-validation
8Production & DeploymentMEDIUMdeploy-backup, deploy-configuration, deploy-reverse-proxy, deploy-sqlite-considerations, deploy-rate-limiting
优先级类别影响程度规则
1集合设计关键coll-field-types, coll-auth-vs-base, coll-relations, coll-indexes, coll-view-collections, coll-geopoint
2API规则与安全关键rules-basics, rules-filter-syntax, rules-request-context, rules-cross-collection, rules-locked-vs-open
3身份验证关键auth-password, auth-oauth2, auth-token-management, auth-mfa, auth-impersonation
4SDK使用高sdk-initialization, sdk-auth-store, sdk-error-handling, sdk-auto-cancellation, sdk-filter-binding, sdk-field-modifiers, sdk-send-hooks
5查询性能高query-pagination, query-expand, query-field-selection, query-batch-operations, query-n-plus-one, query-first-item, query-back-relations
6实时功能中realtime-subscribe, realtime-events, realtime-auth, realtime-reconnection
7文件处理中file-upload, file-serving, file-validation
8生产与部署中deploy-backup, deploy-configuration, deploy-reverse-proxy, deploy-sqlite-considerations, deploy-rate-limiting

Quick Reference

快速参考

Collection Design (CRITICAL)

集合设计（关键）

  • coll-field-types: Use appropriate field types (json for objects, select for enums)
  • coll-auth-vs-base: Extend auth collection for users, base for non-auth data
  • coll-relations: Use relation fields, not manual ID strings
  • coll-indexes: Create indexes on frequently filtered/sorted fields
  • coll-view-collections: Use views for complex aggregations
  • coll-geopoint: Store coordinates as json field with lat/lng
  • coll-field-types：使用合适的字段类型（对象用json，枚举用select）
  • coll-auth-vs-base：为用户扩展auth集合，非认证数据使用base集合
  • coll-relations：使用关联字段，而非手动ID字符串
  • coll-indexes：在频繁过滤/排序的字段上创建索引
  • coll-view-collections：使用视图处理复杂聚合
  • coll-geopoint：将坐标存储为包含lat/lng的json字段

API Rules (CRITICAL)

API规则（关键）

  • rules-basics: Always set API rules; empty = public access
  • rules-filter-syntax: Use @request.auth, @collection, @now in rules
  • rules-request-context: Access request data via @request.body, @request.query
  • rules-cross-collection: Use @collection.name.field for cross-collection checks
  • rules-locked-vs-open: Start locked, open selectively
  • rules-basics：始终设置API规则；空规则意味着公共访问
  • rules-filter-syntax：在规则中使用@request.auth、@collection、@now
  • rules-request-context：通过@request.body、@request.query访问请求数据
  • rules-cross-collection：使用@collection.name.field进行跨集合检查
  • rules-locked-vs-open：从锁定模式开始，选择性开放

Authentication (CRITICAL)

身份验证（关键）

  • auth-password: Use authWithPassword for email/password login
  • auth-oauth2: Configure OAuth2 providers via Admin UI
  • auth-token-management: Store tokens securely, refresh before expiry
  • auth-mfa: Enable MFA for sensitive applications
  • auth-impersonation: Use impersonation for admin actions on behalf of users
  • auth-password：使用authWithPassword进行邮箱/密码登录
  • auth-oauth2：通过Admin UI配置OAuth2提供商
  • auth-token-management：安全存储令牌，在过期前刷新
  • auth-mfa：为敏感应用启用MFA
  • auth-impersonation：使用模拟功能代表用户执行管理员操作

SDK Usage (HIGH)

SDK使用（高）

  • sdk-initialization: Initialize client once, reuse instance
  • sdk-auth-store: Use AsyncAuthStore for React Native/SSR
  • sdk-error-handling: Catch ClientResponseError, check status codes
  • sdk-auto-cancellation: Disable auto-cancel for concurrent requests
  • sdk-filter-binding: Use filter binding to prevent injection
  • sdk-initialization：初始化一次客户端，复用实例
  • sdk-auth-store：在React Native/SSR中使用AsyncAuthStore
  • sdk-error-handling：捕获ClientResponseError，检查状态码
  • sdk-auto-cancellation：为并发请求禁用自动取消
  • sdk-filter-binding：使用过滤绑定防止注入

Query Performance (HIGH)

查询性能（高）

  • query-expand: Expand relations to avoid N+1 queries
  • query-field-selection: Select only needed fields
  • query-pagination: Use cursor pagination for large datasets
  • query-batch-operations: Batch creates/updates when possible
  • query-expand：扩展关联以避免N+1查询
  • query-field-selection：仅选择需要的字段
  • query-pagination：对大型数据集使用游标分页
  • query-batch-operations：尽可能批量创建/更新

Realtime (MEDIUM)

实时功能（中）

  • realtime-subscribe: Subscribe to specific records or collections
  • realtime-events: Handle create, update, delete events separately
  • realtime-auth: Realtime respects API rules automatically
  • realtime-reconnection: Implement reconnection logic
  • realtime-subscribe：订阅特定记录或集合
  • realtime-events：分别处理创建、更新、删除事件
  • realtime-auth：实时功能自动遵循API规则
  • realtime-reconnection：实现重连逻辑

File Handling (MEDIUM)

文件处理（中）

  • file-upload: Use FormData for uploads, set proper content types
  • file-serving: Use pb.files.getURL() for file URLs
  • file-validation: Validate file types and sizes server-side
  • file-upload：使用FormData上传，设置正确的内容类型
  • file-serving：使用pb.files.getURL()获取文件URL
  • file-validation：在服务端验证文件类型和大小

Deployment (MEDIUM)

部署（中）

  • deploy-backup: Schedule regular backups of pb_data
  • deploy-configuration: Use environment variables for config
  • deploy-reverse-proxy: Put behind nginx/caddy in production
  • deploy-sqlite-considerations: Optimize SQLite for production workloads
  • deploy-backup：定期备份pb_data
  • deploy-configuration：使用环境变量配置
  • deploy-reverse-proxy：生产环境中部署在nginx/caddy反向代理之后
  • deploy-sqlite-considerations：针对生产工作负载优化SQLite

Detailed Rules

详细规则

For complete rule documentation with code examples, see AGENTS.md.
如需包含代码示例的完整规则文档，请查看AGENTS.md。