摘要: AgentStation 為了提升開(kāi)發(fā)者體驗(yàn)，創(chuàng)建了 uuidkey 包，將 UUID 編碼成美觀易讀的 API 密鑰。該包支持 UUIDv7，并可解碼密鑰以便數(shù)據(jù)庫(kù)排序和索引。

問(wèn)題：

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

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

我們對(duì) API 密鑰提出了以下要求：

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

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

我們拒絕的 ID：

過(guò)于隨機(jī)、容易猜測(cè)、外觀難看……都不盡如人意。

• 整數(shù)和 BigInt： 簡(jiǎn)單易讀，易于排序。但它們會(huì)暴露密鑰數(shù)量，且容易猜測(cè)，安全性不足。
• NanoIDs： 提供完全隨機(jī)、可自定義的 ID，特別適合面向公眾的標(biāo)識(shí)符。但缺乏用于排序和調(diào)試的時(shí)間戳信息。
• UUIDs： 行業(yè)標(biāo)準(zhǔn)，有兩個(gè)版本值得考慮：
  • UUIDv4：純隨機(jī)字符，簡(jiǎn)單有效。
  • UUIDv7：包含時(shí)間戳，便于調(diào)試和數(shù)據(jù)庫(kù)查詢(xún)排序。
• ULIDs： 包含時(shí)間戳并使用 Base32 編碼，提高可讀性。但我們更傾向于 UUID 原生的 Postgres 支持，且其美觀性仍不足。

我們的解決方案：

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

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

結(jié)果：

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

我們的密鑰：

• 31 個(gè)字符（不含破折號(hào)為 28 個(gè)），比 UUID 的 36 個(gè)字符更短。
• 高度可讀的段落，包含 4 組 7 個(gè)大寫(xiě)字母和數(shù)字，具有“塊狀”的美感和可讀性。
• 以解碼后的 UUID 形式存儲(chǔ)時(shí)，可以按時(shí)間順序排序。
• 用戶(hù)可見(jiàn)的密鑰中時(shí)間戳被模糊處理（但精通技術(shù)的使用者仍然可以解碼）。我們認(rèn)為密鑰中的時(shí)間戳元數(shù)據(jù)是一個(gè)額外的好處，您也可以選擇使用 UUIDv4！

為什么選擇 UUIDv7？

除了時(shí)間戳的優(yōu)勢(shì)外，UUIDv7 將在 Postgres v18 中獲得原生支持。雖然目前可以使用擴(kuò)展在服務(wù)器端生成 UUIDv7，但原生 Postgres 支持的性能肯定會(huì)更好，并且可以很好地與 uuidkey.Encode() 配合使用。

在我們的實(shí)現(xiàn)中，我們目前在應(yīng)用程序?qū)由擅荑€，并將其作為 UUID 存儲(chǔ)以進(jìn)行排序和索引。一旦發(fā)布 Postgres v18，我們將切換到 Postgres 生成，以減輕應(yīng)用程序?qū)拥呢?fù)載并獲得更好的性能。

為什么選擇 Crockford Base32？

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

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

為什么使用破折號(hào)？

帶破折號(hào)的密鑰“塊狀”且對(duì)稱(chēng)。如果將各個(gè)字符灰顯，它們看起來(lái)幾乎像條形碼。我們認(rèn)為這使得快速讀取密鑰的一部分以識(shí)別它變得容易。

破折號(hào)確實(shí)會(huì)移除方便的雙擊復(fù)制功能，但我們認(rèn)為這是為了可讀性而值得的權(quán)衡。我們不希望用戶(hù)到處復(fù)制粘貼它們，事實(shí)上我們希望它們得到謹(jǐn)慎處理。理想情況下，用戶(hù)只在我們的儀表盤(pán)中生成密鑰時(shí)復(fù)制一次密鑰——因此我們?cè)?UI 中添加了一個(gè)復(fù)制按鈕來(lái)解決這個(gè)問(wèn)題。

uuidkey 包：

我們?cè)?github.com/agentstation/uuidkey 上開(kāi)源了這些設(shè)計(jì)選擇。如果您認(rèn)同我們的美學(xué)、推理和對(duì)稱(chēng)性，并希望擁有自己美觀的 API 密鑰，歡迎試用我們的開(kāi)源項(xiàng)目。

uuidkey 包的核心是通過(guò) Base32-Crockford 編解碼器將 UUID 編碼為可讀的密鑰格式，并將其解碼回 UUID。

編碼：

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

解碼：

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

該包旨在與遵循官方 UUID 規(guī)范 (RFC 4122) 的任何 UUID 配合使用，但我們專(zhuān)門(mén)測(cè)試并維護(hù)與兩個(gè)最流行的 UUID Go 生成器的兼容性：

• Gofrs
• Google

安裝很簡(jiǎn)單：

<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>

我們努力將開(kāi)銷(xiāo)降至最低：

性能基準(zhǔn)測(cè)試數(shù)據(jù)已在原文中給出，此處不再贅述。

貢獻(xiàn)給 uuidkey：

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

如果您覺(jué)得它有用或有改進(jìn)建議，我們很樂(lè)意在我們的 GitHub issues 或 Discord 社區(qū)中聽(tīng)到您的意見(jiàn)。

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

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

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

總結(jié)：

在 AgentStation，我們正在構(gòu)建一個(gè)平臺(tái)，讓 AI 代理?yè)碛凶约旱奶摂M工作站來(lái)運(yùn)行瀏覽器、參加會(huì)議和執(zhí)行代碼。隨著我們擴(kuò)展到數(shù)千個(gè)工作站，擁有可排序、高性能的密鑰是實(shí)用的基礎(chǔ)設(shè)施。

但我們也相信，開(kāi)發(fā)者像我們一樣欣賞對(duì)稱(chēng)的美好事物，即使是 API 密鑰。

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

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

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