convex-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Convex Development

Convex开发

Best practices for robust, secure, performant, cost-effective Convex backends.

构建健壮、安全、高性能且具成本效益的Convex后端的最佳实践。

Core Principle

核心原则

Deep modules via the
convex/model/
pattern. Most logic should be plain TypeScript; query/mutation wrappers should be thin.

convex/
  _generated/         # MUST commit to git!
  model/              # Business logic (testable, reusable)
  users.ts            # Public API (thin wrappers)
  schema.ts

通过
convex/model/
模式实现深度模块化。大部分逻辑应采用纯TypeScript编写；查询/变更包装器应尽可能精简。

convex/
  _generated/         # 必须提交至git！
  model/              # 业务逻辑（可测试、可复用）
  users.ts            # 公开API（轻量包装器）
  schema.ts

Critical Rules

关键规则

ALWAYS commit
convex/_generated/
- Required for type-checking, CI/CD, team productivity
Index what you query -
```
.withIndex()
```
not
```
.filter()
```
for efficient queries
Compound indexes for multi-field filters - If querying
```
userId + status
```
, create index
```
["userId", "status"]
```
to filter at index level, not post-fetch
Paginate everything - Never unbounded
```
.collect()
```
on user-facing queries
Trust
ctx.auth
only - Never user-provided auth data

务必提交
convex/_generated/
- 这是类型检查、CI/CD、团队协作效率的必要条件
为查询创建索引 - 使用
```
.withIndex()
```
而非
```
.filter()
```
来实现高效查询
为多字段过滤创建复合索引 - 如果查询
```
userId + status
```
，创建索引
```
["userId", "status"]
```
以在索引层面完成过滤，而非在获取数据后再处理
所有查询均需分页 - 面向用户的查询绝不能使用无限制的
```
.collect()
```
仅信任
ctx.auth
- 绝不使用用户提供的认证数据

Quick Reference

快速参考

Need	Use
Read data reactively	`query`
Write to database	`mutation`
External APIs, vector search	`action`
Scheduled tasks	`internalMutation` / `internalAction`

需求	用法
响应式读取数据	`query`
写入数据库	`mutation`
外部API调用、向量搜索	`action`
定时任务	`internalMutation` / `internalAction`

Anti-Patterns Scanner

反模式扫描器

Run

scripts/anti_patterns_scanner.py ./convex

to detect common issues.

运行

scripts/anti_patterns_scanner.py ./convex

以检测常见问题。

Detailed References

详细参考资料

For comprehensive guidance, see:

```
references/cost-mitigation.md
```
- Bandwidth optimization, indexing, pagination
```
references/embeddings-vectors.md
```
- Vector search patterns, co-location decisions
```
references/query-performance.md
```
- Compound indexes, query segmentation, caching
```
references/security-access.md
```
- Auth patterns, RLS, RBAC, convex-helpers
```
references/schema-migrations.md
```
- Expand/Contract pattern, environment management
```
references/architectural-patterns.md
```
- File organization, state machines, naming

如需全面指导，请参阅：

```
references/cost-mitigation.md
```
- 带宽优化、索引、分页
```
references/embeddings-vectors.md
```
- 向量搜索模式、共置决策
```
references/query-performance.md
```
- 复合索引、查询拆分、缓存
```
references/security-access.md
```
- 认证模式、RLS、RBAC、convex-helpers
```
references/schema-migrations.md
```
- 扩展/收缩模式、环境管理
```
references/architectural-patterns.md
```
- 文件组织、状态机、命名规范

Philosophy

设计理念

Cost First: Bandwidth is often the largest cost. Index aggressively, paginate everything.
Security First: Never trust client input. Always use
```
ctx.auth
```
.
Reactivity is Power: Use
```
useQuery
```
for real-time updates; don't forfeit with one-off fetches.
Type Safety End-to-End: Leverage Convex's full type chain from database to UI.

成本优先：带宽通常是最大的成本支出。积极创建索引，所有查询均需分页。
安全优先：绝不信任客户端输入。始终使用
```
ctx.auth
```
。
响应性即优势：使用
```
useQuery
```
实现实时更新；不要通过一次性获取数据放弃这一优势。
端到端类型安全：充分利用Convex从数据库到UI的完整类型链。