製作漂亮的 API 金鑰

摘要: AgentStation 為了提升開發者體驗，創建了 uuidkey 包，將 UUID 編碼成美觀易讀的 API 密鑰。該套件支援 UUIDv7，並可解碼密鑰以便資料庫排序和索引。

問題：

API 金鑰是使用者與 AgentStation 產品初次互動的重要環節。我們希望密鑰既美觀又易用，但業界似乎缺乏統一標準。作為一家以開發者為中心的新創公司，我們投入時間和精力尋找理想的解決方案。

大多數 API 金鑰都很糟糕：

我們對 API 金鑰提出了以下要求：

• 安全
• 全域唯一
• 可排序
• 在 Postgres 中效能優異
• 外觀美觀

然而，大多數 API 金鑰都缺乏美感，通常是格式不一致的隨機字符，難以閱讀、排序和識別。 我們希望 API 金鑰也具備美感，如同生活中美好的事物一樣對稱。

我們拒絕的 ID：

過於隨機、容易猜測、外觀難看……都不盡人意。

• 整數和 BigInt： 簡單易讀，易於排序。但它們會暴露密鑰數量，且容易猜測，安全性不足。
• NanoIDs： 提供完全隨機、可自訂的 ID，特別適合面向大眾的識別碼。但缺乏用於排序和調試的時間戳資訊。
• UUIDs： 業界標準，有兩個版本值得考慮：
  • UUIDv4：純隨機字符，簡單有效。
  • UUIDv7：包含時間戳，方便除錯和資料庫查詢排序。
• ULIDs： 包含時間戳並使用 Base32 編碼，提高可讀性。但我們更傾向於 UUID 原生的 Postgres 支持，且其美觀仍不足。

我們的解：

由於現有方案的美觀性（對稱性）不足，我們創建了自己的方法：

1. 使用 UUIDv7 作為基礎 ID，利用時間戳資訊。
2. 使用 Crockford Base32 編碼提高可讀性。
3. 添加美觀的破折號以增強視覺效果。

結果：

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

我們的金鑰：

• 31 個字元（不含破折號為 28 個），比 UUID 的 36 個字元更短。
• 高度可讀的段落，包含 4 組 7 個大寫字母和數字，具有「塊狀」的美感和可讀性。
• 以解碼後的 UUID 形式儲存時，可以按時間順序排序。
• 使用者可見的金鑰中時間戳被模糊處理（但精通技術的使用者仍然可以解碼）。我們認為金鑰中的時間戳記資料是額外的好處，您也可以選擇使用 UUIDv4！

為什麼選擇 UUIDv7？

除了時間戳記的優勢外，UUIDv7 將在 Postgres v18 中獲得原生支援。雖然目前可以使用擴充功能在伺服器端產生 UUIDv7，但原生 Postgres 支援的效能肯定會更好，並且可以很好地與 uuidkey.Encode() 配合使用。

在我們的實作中，我們目前在應用程式層產生金鑰，並將其作為 UUID 儲存以進行排序和索引。一旦發布 Postgres v18，我們將切換到 Postgres 生成，以減輕應用程式層的負載並獲得更好的效能。

為什麼選擇 Crockford Base32？

我們選擇 Crockford Base32 編碼是因為它：

• 只使用大寫字母和數字，提高了可讀性。
• 將密鑰長度減少約 1/5。
• 映射高效且可預測。

為什麼要用破折號？

有破折號的金鑰「塊狀」且對稱。如果將各個字元灰顯，它們看起來幾乎像是條碼。我們認為這使得快速讀取密鑰的一部分以識別它變得容易。

破折號確實會移除方便的雙擊複製功能，但我們認為這是為了可讀性而值得的權衡。我們不希望用戶到處複製貼上它們，事實上我們希望它們得到謹慎處理。理想情況下，使用者只在我們的儀表板中產生金鑰時複製一次金鑰——因此我們在 UI 中新增了一個複製按鈕來解決這個問題。

uuidkey 包裝：

我們在 github.com/agentstation/uuidkey 上開源了這些設計選擇。如果您認同我們的美學、推理和對稱性，並希望擁有自己美觀的 API 金鑰，歡迎試用我們的開源專案。

uuidkey 套件的核心是透過 Base32-Crockford 編解碼器將 UUID 編碼為可讀的金鑰格式，並將其解碼回 UUID。

編碼：

程式碼片段已在原文中給出，此處不再贅述。

解碼：

程式碼片段已在原文中給出，此處不再贅述。

該套件旨在與遵循官方 UUID 規範 (RFC 4122) 的任何 UUID 配合使用，但我們專門測試並維護與兩個最流行的 UUID Go 生成器的兼容性：

• Gofrs
• Google

安裝很簡單：

<code>key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X</code>

基本用法：

<code>go get github.com/agentstation/uuidkey</code>

我們努力將開銷降至最低：

效能基準測試資料已在原文中給出，此處不再贅述。

貢獻給 uuidkey：

我們致力於維護 uuidkey 作為可靠的開源工具，因為我們在生產中使用它——歡迎貢獻！

如果您覺得它有用或有改進建議，我們很樂意在我們的 GitHub issues 或 Discord 社群中聽到您的意見。

先前技術與巨人肩膀：

在我們發布項目後，我們發現了一些具有類似實現的項目，但仍然沒有滿足我們使用 Go 編碼和解碼 UUID 的標準。

• uuidapikey - Go，但不支援編碼或解碼 UUID 輸入。
• based_uuid - Ruby，但用於公用 ID。

總結：

在 AgentStation，我們正在建立一個平台，讓 AI 代理程式擁有自己的虛擬工作站來運行瀏覽器、參加會議和執行程式碼。隨著我們擴展到數千個工作站，擁有可排序、高效能的密鑰是實用的基礎設施。

但我們也相信，開發者像我們一樣欣賞對稱的美好事物，即使是 API 金鑰。

我們希望您發現 uuidkey 既實用又美觀。

腳註已在原文中給出，此處不再贅述。

以上是製作漂亮的 API 金鑰的詳細內容。更多資訊請關注PHP中文網其他相關文章！