Convex Components 指南用于帮助开发者封装功能，构建可维护、可复用的后端。
用途
组件是自包含的迷你后端，打包了自身的数据库模式、函数（查询、变更、动作）以及隔离的数据表，并具有清晰的 API 边界。可将其理解为后端领域的 npm 包，或省去部署复杂度的微服务。其目的是把认证、存储、支付、通知、分析等横切功能从业务代码中剥离，让主应用只保留真正的业务逻辑。指南通过单体代码与组件化代码的目录对比说明这一价值：单体方式下 users、files、payments 等文件各自数百行且相互混杂，组件方式则把可复用能力放入 components 目录，业务域文件变得精简。
主要能力
指南讲解以下主题：什么是 Convex 组件；为何使用组件；快速开始（安装、在 convex.config.ts 中配置、在代码中使用）；兄弟组件模式（同一层级多个组件各负责一件事，由主应用编排调用）；官方组件目录分类，包括 Authentication（如 @convex-dev/better-auth）、Storage（如 @convex-dev/r2、@convex-dev/storage）、Payments（如 @convex-dev/polar）、AI（如 @convex-dev/agent、@convex-dev/embeddings）、Backend Utilities（如 @convex-dev/ratelimiter、@convex-dev/aggregate、@convex-dev/action-cache、@convex-dev/sharded-counter、@convex-dev/migrations、@convex-dev/workflow）；创建自定义组件；组件通信模式；最佳实践与检查清单。
使用方式
指南给出的使用步骤为：一、通过 npm 安装组件，例如 npm install @convex-dev/ratelimiter；二、在 convex.config.ts 中使用 defineApp 注册组件；三、在业务代码中通过生成的 components API 调用，例如在 mutation 中调用 components.ratelimiter.check 传入 key、limit、period 等参数。指南还提供订阅功能的示例，展示如何依次调用 auth、payments、analytics、emails 等兄弟组件，并将结果写回主应用数据表。
自建组件的场景与结构
适合创建组件的情形：功能自包含、会跨项目复用、希望与团队或社区共享、功能复杂且有自身数据模型、作为第三方集成的封装。不适合的情形：一次性业务逻辑、与主应用紧耦合、简单工具函数。结构示例包含组件的 convex.config.ts（defineComponent）、schema.ts（defineSchema 与 defineTable，含索引定义）、send.ts（mutation）与 read.ts（query）。
通信模式与限制
指南区分了允许与禁止的通信方式：主应用调用组件、主应用编排多个兄弟组件、组件接收来自父级的数据（传入父表 ID，组件以字符串/ID 形式存储但不直接访问父表）均被认可；组件直接访问父表、组件之间直接互相调用则被禁止，若需要此类调用应放入主应用或重构设计。
最佳实践
包括单一职责（每个组件只做好一件事，避免大一统的 utils 组件）、清晰的 API 表面（只导出必要接口，内部实现保持私有）、最小耦合（以参数传数据）、为组件做版本管理、为组件编写文档（说明用途、安装、使用、API 参考与示例）。检查清单涵盖浏览组件目录、通过 npm 安装、在 convex.config.ts 配置、使用兄弟组件封装功能、为可复用功能自建组件、保持组件聚焦、隔离测试组件、记录组件 API 并正确版本化。