TanStack 产品准则

这些准则定义了指导每个 TanStack 库和产品的核心原则。它们既是开发者对我们的工具的期望质量标准,也是评估贡献、特性和想法的参考。

这些准则补充了我们的 组织准则,涵盖我们的业务价值观和独立性。两者结合,确保 TanStack 始终致力于构建能够让网络对开发者更友好的工具——按照您的意愿,毫不妥协。

1. 开放、独立、技术无关

每个 TanStack 库都从一个与提供者无关的核心开始,确保开发者永远不会被锁定到特定的供应商、平台或生态系统。集成作为可选的适配器分层在其之上——绝不会作为基础。

中立核心,可选集成: 每个 TanStack 库都从一个与提供者无关的核心开始(框架、运行时、供应商或服务),集成作为可选的适配器分层在其之上——绝不会作为基础。
可移植性高于深度锁定: 我们设计 API,以便在不重写业务逻辑的情况下,更换提供者、平台或运行时是可行的;任何特定于提供者的行为都将明确隔离。
跨提供者的统一抽象: 当多个供应商/服务解决类似问题时,我们提供一致的抽象,使它们从开发者的角度来看可以互换。
我们不追求每一个细分特性: 我们有意避免模拟每个供应商的每个定制特性;我们专注于大多数团队真正需要的共享、高价值能力。
优雅降级,而非碎片化: 当提供者提供额外的功能时,它们会插入扩展点或可选层,而不是碎片化核心抽象或决定其形状。

这排除了什么

  • 核心中带有供应商偏见的 API 或由合作伙伴驱动的特性
  • 引入平台偏见或“我们全力以赴 X 供应商”假设的贡献
  • 需要承诺特定云提供商或部署模型的特性

2. 可组合、平台对齐的原始组件

我们构建专注、可组合的原始组件,拥抱平台而不是隐藏它。每个库都应该能够逐步采用,而无需重写或创建对其他 TanStack 工具的硬依赖。

原始组件优先于框架: 我们发布专注、可组合的构建块,而不是包罗万象的“一个框架统治它们”抽象。
拥抱平台: 我们利用网络、HTTP、JS/TS 和服务器,而不是将其隐藏在不透明的魔法层之后。
渐进式采用: 每个库都应该能够一次采用一部分,而无需重写或与 TanStack 的其余部分进行硬耦合。
设计上的逃生口: 始终必须能够降低级别,与现有系统集成,或在必要时绕过我们的抽象。

这排除了什么

  • 需要完全重写或“全力以赴”承诺的设计
  • 大量的全局单例或 TanStack 库之间的硬依赖
  • 隐藏平台能力而不提供明确逃生路线的抽象

3. 务实、生产级质量

我们围绕现实世界的生产用例、边缘情况和长期应用程序进行设计——而不仅仅是理想化的演示。性能和可扩展性是要求,而不是锦上添花。

真实产品作为标准: 我们围绕现实世界的工作负载、边缘情况和长期应用程序进行设计——而不仅仅是理想化的演示。
“今天发布”的质量: 在我们的收入关键型应用程序中运行,我们才会觉得特性完成。
性能和规模作为要求: 渲染、缓存和网络行为必须在规模下保持稳定;性能不是锦上添花。
值得其成本的 DX: API 人体工程学、工具和文档应该可衡量地改善开发人员的结果,而不是增加精巧的仪式。

这排除了什么

  • 仅用于演示的特性,无法承受现实世界的负载
  • 当出现问题时,无法调试或推理的魔法
  • 优化基准测试而非现实世界可靠性的更改

4. 可预测、明确、类型安全的行为

我们最大限度地减少魔法并最大限度地提高清晰度。状态、副作用和数据流应该从代码中理解,而不是从隐藏行为中猜测。类型安全应该指导正确的使用,而不会让用户淹没在泛型中。

最少的魔法,最大的清晰度: 状态、副作用和数据流必须从代码中理解,而不是从隐藏行为中猜测。
显式优于隐式: 重要的行为在 API 和配置中是明确的,令人惊讶的默认值被视为错误。
类型安全作为杠杆,而非教条: TypeScript 支持应该指导正确的使用并捕获真实错误,而不会让用户淹没在泛型中。
稳定的 API 和迁移: 我们小心地演进,提供清晰的 changelog 和迁移路径;为了风格或炒作而破坏是不可以接受的。

这排除了什么

  • 隐藏的全局状态或 API 中不明显的副作用
  • 没有清晰迁移路径的反向不兼容 API 变更
  • 在技术上正确但实际上无法使用的类型签名

如何使用这些准则

这些准则为不同的受众提供多种用途

对于评估 TanStack 的开发者

这些准则定义了您可以期望从我们的库中获得的内容——质量、可移植性和对您自由组合和部署的承诺。

对于贡献者

在提出特性或更改时,请考虑它们与这些准则的对齐程度。如果您的想法与准则冲突,请明确说明原因以及如何证明冲突是合理的。

对于维护者和审查者

在评估 PR、功能请求和架构决策时,将这些准则用作检查清单。如果某件事威胁到准则,则需要强有力的理由或应该被拒绝。

对于合作伙伴

这些准则确保我们的库保持中立和以开发者为中心。合作伙伴集成必须尊重这些原则,并且不能将核心 API 偏向于特定的平台或供应商。

这些准则与我们的 组织准则一起工作,涵盖我们的业务独立性、可持续性和对开放网络的承诺。两者结合,确保 TanStack 始终坚持其使命:构建能够让网络对开发者更友好的工具——按照您的意愿。