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

問題：

API 金鑰是使用者與 AgentStation 產(chǎn)品初次互動的重要環(huán)節(jié)。我們希望密鑰既美觀又易用，但業(yè)界似乎缺乏統(tǒng)一標(biāo)準(zhǔn)。作為一家以開發(fā)者為中心的新創(chuàng)公司，我們投入時間和精力尋找理想的解決方案。

大多數(shù) API 金鑰都很糟糕：

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

• 安全
• 全域唯一
• 可排序
• 在 Postgres 中效能優(yōu)異
• 外觀美觀

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

我們拒絕的 ID：

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

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

我們的解：

由於現(xiàn)有方案的美觀性（對稱性）不足，我們創(chuàng)建了自己的方法：

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

結(jié)果：

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

我們的金鑰：

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

為什麼選擇 UUIDv7？

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

在我們的實(shí)作中，我們目前在應(yīng)用程式層產(chǎn)生金鑰，並將其作為 UUID 儲存以進(jìn)行排序和索引。一旦發(fā)布 Postgres v18，我們將切換到 Postgres 生成，以減輕應(yīng)用程式層的負(fù)載並獲得更好的效能。

為什麼選擇 Crockford Base32？

我們選擇 Crockford Base32 編碼是因?yàn)樗?/p>

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

為什麼要用破折號？

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

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

uuidkey 包裝：

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

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

編碼：

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

解碼：

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

該套件旨在與遵循官方 UUID 規(guī)範(fàn) (RFC 4122) 的任何 UUID 配合使用，但我們專門測試並維護(hù)與兩個最流行的 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>

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

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

貢獻(xiàn)給 uuidkey：

我們致力於維護(hù) uuidkey 作為可靠的開源工具，因?yàn)槲覀冊谏a(chǎn)中使用它——?dú)g迎貢獻(xiàn)！

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

先前技術(shù)與巨人肩膀：

在我們發(fā)布項(xiàng)目後，我們發(fā)現(xiàn)了一些具有類似實(shí)現(xiàn)的項(xiàng)目，但仍然沒有滿足我們使用 Go 編碼和解碼 UUID 的標(biāo)準(zhǔn)。

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

總結(jié)：

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

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

我們希望您發(fā)現(xiàn) uuidkey 既實(shí)用又美觀。

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

以上是製作漂亮的 API 金鑰的詳細(xì)內(nèi)容。更多資訊請關(guān)注PHP中文網(wǎng)其他相關(guān)文章！