美しい API キーの作成

概要: 開発者のエクスペリエンスを向上させるために、AgentStation は、UUID を美しく読みやすい API キーにエンコードするための uuidkey パッケージを作成しました。このパッケージは UUIDv7 をサポートしており、データベースの並べ替えとインデックス作成のためのキーをデコードできます。

質問:

API キーは、ユーザーが AgentStation 製品と最初にやり取りする際の重要な部分です。キーは美しく、使いやすいものであることが望まれますが、業界には標準が不足しているようです。開発者中心のスタートアップとして、私たちは理想的なソリューションを見つけるために時間と労力を投資しています。

ほとんどの API キーは最悪です:

API キーには次の要件があります:

• 安全性
• 世界的にユニーク
• 並べ替え可能
• Postgres での優れたパフォーマンス
• 美しい外観

しかし、ほとんどの API キーは美観に欠けており、一貫性のないランダムな文字であることが多く、読み取り、並べ替え、識別が困難です。 私たちは、API キーが、人生の良いもののように、見た目が美しく、対称的であることを望んでいます。

拒否された ID:

ランダムすぎる、推測しやすい、見た目が醜い...すべてが満足できません。

• 整数と BigInt: 読みやすく、並べ替えも簡単です。しかし、キーの数が公開され、推測が容易で、セキュリティが不十分です。
• NanoID: 完全にランダムなカスタマイズ可能な ID を提供し、公開識別子に最適です。ただし、並べ替えやデバッグのためのタイムスタンプ情報が不足しています。
• UUID: 業界標準。検討に値する 2 つのバージョンがあります:
  • UUIDv4: 純粋にランダムな文字、シンプルかつ効果的。
  • UUIDv7: デバッグとデータベース クエリの並べ替えを容易にするタイムスタンプが含まれています。
• ULID: にはタイムスタンプが含まれており、可読性を高めるために Base32 を使用してエンコードされます。しかし、私たちは UUID ネイティブ Postgres サポートを好みますが、その美しさはまだ不十分です。

私たちのソリューション:

既存のソリューションには美学 (対称性) が欠けているため、独自のアプローチを作成しました。

1. ベース ID として UUIDv7 を使用し、タイムスタンプ情報を利用します。
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 文字より短い。
• 7 つの大文字と数字の 4 セットを含む可読性の高い段落。「ブロック状」の美しさと可読性を備えています。
• デコードされた UUID として保存すると、時系列に並べ替えることができます。
• ユーザーに表示されるキーのタイムスタンプは難読化されています (ただし、技術に精通したユーザーはデコードできます)。キー内のタイムスタンプ メタデータは追加のボーナスであると考えており、UUIDv4 の使用を選択することもできます。

UUIDv7 を選択する理由?

タイムスタンプの利点に加えて、UUIDv7 は Postgres v18 でネイティブ サポートを受ける予定です。現在、拡張機能を使用してサーバー側で UUIDv7 を生成することは可能ですが、ネイティブの Postgres サポートは間違いなくパフォーマンスが向上し、uuidkey.Encode() とうまく連携するでしょう。

私たちの実装では現在、アプリケーション層でキーを生成し、並べ替えとインデックス付けのためにそれらを UUID として保存しています。 Postgres v18 がリリースされたら、アプリケーション層の負荷を軽減し、より良いパフォーマンスを達成するために Postgres ビルドに切り替える予定です。

Crockford Base32 を選ぶ理由?

Crockford Base32 エンコードを選択した理由は次のとおりです。

• 読みやすくするために、大文字と数字のみを使用してください。
• キーの長さを約 1/5 に短縮します。
• マッピングは効率的で予測可能です。

ダッシュを使用する理由

ダッシュ キーは「ブロック状」で対称的です。個々の文字をグレーアウトすると、まるでバーコードのように見えます。これにより、キーの一部をすばやく読み取って識別することが容易になると考えられます。

ダッシュにより、便利なダブルクリックのコピー機能が削除されますが、これは読みやすさとのトレードオフとして価値があると考えています。私たちは、ユーザーがそれらをどこにでもコピーして貼り付けることを望んでいません。実際、私たちはそれらを慎重に扱ってほしいと考えています。理想的には、ユーザーはダッシュボードでキーを生成するときにキーを 1 回だけコピーする必要があるため、この問題を解決するために UI にコピー ボタンを追加しました。

uuidkey パッケージ:

これらの設計の選択肢は、github.com/agentstation/uuidkey でオープンソース化されています。私たちの美学、推論、対称性に同意し、独自の美しい API キーを取得したい場合は、遠慮なく私たちのオープンソース プロジェクトを試してみてください。

uuidkey パッケージの中核は、Base32-Crockford コーデックを介して UUID を読み取り可能なキー形式にエンコードし、それをデコードして UUID に戻すことです。

エンコーディング:

コード スニペットは原文に記載されているため、ここでは繰り返しません。

デコード:

コード スニペットは原文に記載されているため、ここでは繰り返しません。

このパッケージは、公式 UUID 仕様 (RFC 4122) に従う任意の UUID で動作するように設計されていますが、特に最も人気のある 2 つの UUID Go ジェネレーターとの互換性をテストし、維持しています。

• ゴファー
• 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 の問題または Discord コミュニティでご意見をお待ちしています。

先行技術と巨人の肩:

プロジェクトをリリースした後、同様の実装を持つプロジェクトがいくつか見つかりましたが、それでも Go を使用した UUID のエンコードとデコードの基準を満たしていませんでした。

• uuidapikey - Go ですが、UUID 入力のエンコードまたはデコードはサポートしていません。
• based_uuid - Ruby、ただしパブリック ID 用。

概要:

AgentStation では、AI エージェントが独自の仮想ワークステーションを使用してブラウザを実行し、会議に出席し、コードを実行できるようにするプラットフォームを構築しています。数千のワークステーションに拡張する場合、ソート可能で高性能なキーを持つことが実用的なインフラストラクチャとなります。

しかし、開発者も私たちと同じように、API キーであっても対称性の美しさを高く評価していると私たちは信じています。

実用的かつ美しい uuidkey を見つけていただければ幸いです。

脚注は原文に記載されているため、ここでは繰り返しません。

以上が美しい API キーの作成の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。