前端 API 密钥重构：Clerk SDK 开发者体验优化实践

一. 重构前端 API 密钥的背景

与大多数开发工具类似，Clerk 的 SDK 配置了两种密钥类型：

• 后端密钥（Backend Key）：具有高度随机性，确保无法被猜测或滥用。
• 前端密钥（Frontend Key）：用于前端与 API 的交互，安全要求相对较低，但需保证唯一性和性能。

尽管前端密钥的安全性低于后端密钥，许多工具仍选择让两者在格式和长度上保持一致。例如 Stripe 的密钥设计就是这种方式：

（示例提示：密钥已被重置，不影响操作）

然而，Clerk 作为专注身份验证的服务提供商，对前端密钥提出了额外要求，使得简单镜像后端密钥设计可能导致性能问题。

二. 前端密钥与性能的关系

前端密钥的核心作用是作为与前端 API 交互的唯一标识符。

以 Stripe SDK 为例，开发者在前端应用中使用的可发布密钥如下：

• 所有请求直接发送到 stripe.com 域。
• 即使组件嵌入到自有网站中，SDK 仍通过 Stripe 域发起请求。

对于 Clerk 来说，这种方式不适用。由于 Clerk 需要运行身份验证 API 并维护用户会话，API 请求必须通过客户的域名访问。因此，开发者需在 DNS 记录中配置 CNAME，确保前端请求属于第一方环境。

这种设计保证了安全性与性能，但也增加了开发者初期配置的复杂度。

三. 初始设计：主机名作为前端密钥

在 Clerk 的早期版本中，前端密钥只是托管前端 API 的主机名。开发者在 React 应用中配置方式如下：

• 通过直接传递 API 主机名，避免了额外 API 请求，提高加载速度。

然而，这种设计引发了开发者困惑：

• 主机名作为前端密钥非常不直观。
• 即使通过命名和文档进行解释，仍无法完全消除误解。
• 开发者在集成过程中频繁反馈此问题，成为潜在障碍。

四. 新的前端 API 密钥设计

为了优化开发者体验，Clerk 对前端 API 密钥进行了重新设计。新方案借鉴了 Stripe 的可发布密钥形式，但保留了性能优化细节。

1. 核心设计特点

• Base64 编码：pk_test_ 后的部分是对旧值进行 Base64 编码后的结果。
• 格式校验：引入 $ 停止字符，用于检测密钥格式是否正确。
• 直观属性名称：调整 React SDK 中属性名称，使配置更易理解。

2. 性能保证

• 新设计在外观上与 Stripe 类似，但不影响原有请求性能。
• 通过隐藏优化逻辑，确保前端 API 调用依然高效。

五. 重构带来的成果

经过前端 API 密钥重构，开发者体验得到显著提升：

• 易用性增强：密钥格式直观，减少了初始配置困惑。
• 性能不受影响：API 请求依然通过客户域名访问，保证身份验证和会话管理效率。
• 集成更顺畅：开发者可快速完成 SDK 集成和身份验证功能的配置。

此次重构展示了在保障安全和性能的前提下，通过优化密钥设计提升开发者体验的实践案例。

原文链接: https://clerk.com/blog/refactoring-our-api-keys