Bruno 身份验证新手入门教程

1- 第一部分：为什么要有 " 身份验证 " 这回事？

想象一下你要去一个俱乐部：

有些俱乐部（公开 API）：
- 大门敞开，谁都可以进去逛逛。—— 这就不需要身份验证。
大多数俱乐部（需要保护的 API）：
- 门口有保安，需要你出示会员卡、身份证或者特定的邀请函才能进入。—— 这就需要身份验证，证明你有权进入。

API 也是一样。很多 API 包含重要数据或功能（比如你的用户信息、银行账户操作），不能随便让陌生人访问。身份验证就是 API 世界里的 " 保安 " 和 " 会员卡 "，确保只有 " 对的人 " 才能使用 API。

Bruno 是一个帮你 " 假装 " 成那个 " 对的人 " 去和 API 打交道的工具。所以，你需要在 Bruno 里设置好 " 会员卡 " 信息，Bruno 才能成功地帮你访问那些需要验证的 API。

2- 第二部分：关键概念 - 在哪里设置 " 会员卡 " 信息？（层级与继承）

这是 Bruno 设计得很棒的地方，能帮你省很多事。你不需要给每个 API 请求都单独配一次 " 会员卡 "。

官方文档 (https://docs.usebruno.com/auth/overview) 提到了设置身份验证的三个层级，像套娃一样：

2.1- 最高层级：集合 (Collection)

好比： 整个俱乐部的通用入场规则。
在 Bruno 里：
- 找到左侧边栏你的 API 集合（比如你项目的所有 API 都放在一个叫 “MyProject APIs” 的集合里）。
- 鼠标悬停在集合名称上，点击出现的三个点 (…) 按钮。
- 选择 “Settings”（设置）。
  - 在弹出的窗口中，找到 Auth（身份验证）标签页。
  - 在这里，你可以选择一种身份验证方式（比如后面会讲的 Basic Auth、Bearer Token 等）并填入信息。
效果： 这个集合里的所有文件夹和请求，默认都会自动使用你在这里设置的身份验证方式。就像俱乐部的基本规则对所有区域都有效。

2.2- 中间层级：文件夹 (Folder)

好比： 俱乐部里的 VIP 包厢有单独的规则。
在 Bruno 里：
- 如果你的集合里创建了文件夹来组织 API 请求（比如一个叫 “User Management” 的文件夹）。
- 鼠标悬停在文件夹名称上，点击出现的三个点 (…) 按钮。
- 选择 “Auth”（身份验证）标签页（或者可能在 “Settings” 里，具体看 Bruno 版本）。
  - 在这里，你可以选择不同于集合的身份验证方式，或者选择 Inherit Auth from Collection（继承集合的认证）——这是默认行为。
效果： 这个文件夹里的所有请求，会优先使用文件夹的设置。如果文件夹选择的是 " 继承 "，那它就用上一级（集合）的设置。就像 VIP 包厢可以有更严或更松的规则，但如果不特别规定，就按俱乐部的通用规则来。

2.3- 最具体层级：请求 (Request)

好比： 进入 VIP 包厢里的某个特定房间（比如储藏室）又有特殊要求。
在 Bruno 里：
- 当你打开一个具体的 API 请求时（比如 “Get User Profile” 这个请求）。
- 在主编辑区的上方，你会看到一排标签页，比如 Params, Headers, Body 等，找到并点击 Auth 标签页。
  - 在这里，你可以为这一个请求单独设置身份验证。
    - 默认情况下，它会显示 Inherit Auth from Parent Folder/Collection（从父级文件夹/集合继承认证）。
效果：
- 这是最优先的设置。如果在这里选择了具体的认证方式（比如 No Auth- 无认证），那么无论上级文件夹或集合设置了什么，都以这个请求的设置为准。
- 就像保安说：" 虽然你有会员卡，但进这个储藏室今天谁都不许进！"

2.4- 核心：继承 (Inheritance)

规则： 请求优先听自己的 -> 再听文件夹的 -> 最后听集合的。
默认： 下级默认 " 听 " 上级的。
覆盖： 你可以在任何下级明确说 " 我不听上级的，我自己来！"，方法就是在该层级的 Auth 标签页选择一个具体的认证类型（或 No Auth）。

3- 第三部分：手把手配置常见的 " 身份验证卡 " 类型

现在我们来看，在 Auth 标签页那个下拉菜单里，不同的选项都是什么意思，怎么填。

3.1- 无认证 (No Auth / None)

含义： 不需要任何 " 会员卡 "，直接进。
何时使用： 访问公开 API，比如获取天气信息、公共新闻等。或者，当你想明确覆盖掉上级设置的认证时。
如何配置： 在 Auth 标签页的下拉菜单里选择 None 或 No Auth。不需要填其他任何东西。

3.2- 基本认证 (Basic Auth)

含义： 最简单的 " 用户名 + 密码 " 会员卡。
何时使用： 一些比较老的或内部的 API 可能还在用。API 文档会告诉你需要用 Basic Auth。
如何配置：
- 在 Auth 标签页下拉菜单选 Basic。
- 你会看到两个输入框：
  - Username：填入 API 提供商给你的用户名。
  - Password：填入对应的密码。
    - 提示：后面会讲用变量更安全！
- 填好后，Bruno 会自动处理，你不用管细节。
背后小知识： Bruno 会把 " 用户名: 密码 " 这串字用一种叫 Base64 的方式编码，然后在发送请求时加一个类似 Authorization: Basic dXNlcjpwYXNz 的标记。

3.3- 承载令牌 (Bearer Token)

含义： 一种很流行的 " 临时通行证 "。你先通过登录或其他方式获取一个叫做 “Token”（令牌）的长字符串，之后每次访问 API 都带上这个令牌，证明你已经认证过了。
何时使用： 非常非常常用！大多数现代 API 都可能用到它。API 文档会告诉你需要 Bearer Token。
如何配置：
- 在 Auth 标签页下拉菜单选 Bearer。
- 你会看到一个输入框：
  - Token：把你的令牌字符串粘贴到这里。
    - 提示：这个令牌通常比较长，也建议用变量！
背后小知识： Bruno 会在发送请求时加一个类似 Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9… 的标记。

3.4- API 密钥 (API Key)

含义： 服务提供商发给你的一个专属 " 钥匙串 "（密钥），用来识别是哪个应用程序在访问 API。
何时使用： 很多 SaaS 服务（比如天气服务、地图服务、AI 服务）会给开发者提供 API Key。
如何配置：
- 在 Auth 标签页下拉菜单选 API Key。
- 你需要填三个东西，这三个信息都需要从 API 文档里查找确认：
  - Key: 这个 " 钥匙 "（API Key）的名字叫什么？API 文档会指定，比如可能是 X-Api-Key, Authorization, api_key 等。填入文档要求的名字。
  - Value: 你的 " 钥匙串 " 本身，那个长长的、唯一的字符串。填入你获取到的 API Key。
    - 提示：强烈建议用变量！
  - Add to: 这个 " 钥匙 " 应该插在哪里？有两个常见位置：
    - Header（请求头）：就像把钥匙别在胸牌上。这是最常见的方式。
    - Query Params（查询参数）：就像把钥匙挂在 URL 的小尾巴上。
      - 你必须看 API 文档才知道应该选哪个！选错了 API 就会拒绝你.
例子： 如果 API 文档说：需要一个名为 X-My-ApiKey 的 Header，值为你的 Keyabc123xyz。
* 那么你在 Bruno 里就填：Key = X-My-ApiKey, Value = abc123xyz, Add to = Header。

3.5- OAuth 2.0

含义： 这是目前最常用、最安全但也最复杂的授权方式。它更像是一个 " 授权流程 "，让你（用户）授权给 Bruno（或其他应用），允许它代表你去访问你的资源（比如你在某个网站上的数据），而不需要把你的密码直接告诉 Bruno。
何时使用： 当你需要访问像 Google、Facebook、GitHub、或者很多企业级应用的 API 时，通常都用 OAuth 2.0。
如何配置：
- 在 Auth 标签页下拉菜单选 OAuth 2。
- 你会看到一大堆配置项！不要慌！这些信息通通来自你要对接的那个 API 的开发者文档（非常重要！）
  - 你需要找到并填入：
    - Grant Type（授权类型）：这是 OAuth 2.0 的核心，决定了获取令牌的流程。常见的有：
      - Authorization Code: 最常见，需要用户登录授权，适合 Web 应用。
      - Client Credentials: 不需要用户参与，适合服务器到服务器的通信。
        
        Password Credentials: （已不推荐）直接用用户名密码换令牌。
        
        Implicit: （已不推荐）简化流程，令牌直接返回给浏览器。
      - API 文档会明确告诉你用哪种 Grant Type！
    - Callback URL/Redirect URL: Bruno（或你的应用）接收授权码的地方。Bruno 通常会提供一个默认值或帮你处理。
    - Auth URL: 用户会被引导去登录和授权的页面的网址。
    - Access Token URL: 用授权码或其他凭证去换取最终访问令牌的 API 地址。
    - Client ID: API 提供商给你的应用的唯一标识。
    - Client Secret: 与 Client ID 配对的密钥，**极其重要，必须保密！（提示：必须用变量！）
    - Scope: 你想请求哪些权限？比如 read_profile, write_posts。API 文档会列出可用的 Scope。
    - 可能还有 State, Audience 等其他字段，根据 API 文档填写。
- 获取令牌：
  - 填完这些信息后，通常会有一个按钮，比如 “Get New Access Token” 或 “Authorize”/“Request Token”。点击它，Bruno 会：
    - 可能弹出一个浏览器窗口让你登录并授权。
    - 在后台与 API 提供商的服务器进行一系列交互。
    - 如果一切顺利，Bruno 会自动获取到 Access Token（访问令牌），并可能还有 Refresh Token（用于刷新过期的访问令牌）。
    - 之后 Bruno 会自动在发送请求时带上这个获取到的 Access Token（通常是以 Bearer Token 的形式）。
关键点：
- OAuth 2.0 的配置完全依赖于第三方 API 的文档。每个服务的配置细节都可能不同。耐心阅读文档是必须的！

3.6- 其他类型 (Digest Auth, AWS SigV4)

Digest Auth:
- 比 Basic Auth 安全一点的用户名/密码认证，不直接传密码，而是通过一系列挑战/应答来验证。配置时也需要用户名和密码。不常用。
AWS Signature v4:
- 专门用于访问亚马逊云服务 (AWS)API 的签名认证方式。
- 配置极其复杂，需要你的 AWS Access Key ID, Secret Access Key, AWS Region, Service Name 等信息。
- 如果你需要和 AWS API 交互，必须仔细阅读 AWS 的官方文档和 Bruno 关于 AWS SigV4 的文档。
如何配置：
- 选择对应的类型，然后根据界面提示和你从服务商文档获取的信息填写。

4- 第四部分：高手秘籍 - 使用环境变量管理 " 钥匙 "

想象一下，你的密码、令牌、API Key 都是非常敏感的 " 钥匙 "。直接把它们写在每个请求的配置里：

不安全：
- 如果你分享你的 Bruno 集合，别人就能看到你的密钥！
难管理：
- 如果你有测试环境和生产环境，它们的密钥通常不同，你得手动改来改去。
易出错：
- 复制粘贴长长的令牌很容易出错。

4.1- 解决方案：使用 Bruno 的环境变量功能

找到环境设置：
1. 通常在 Bruno 界面的左上角或右上角，会有一个眼睛图标👁️或者类似 “Environments”/“No Environment” 的下拉菜单。点击它。
创建环境：
1. 你可以创建不同的环境，比如 Development（开发）, Staging（测试）, Production（生产）。
2. 点击 “Manage Environments” 或类似的按钮，然后 “Create Environment”。
**添加变量：
1. 在你创建的环境里（比如 Development），添加变量。变量是键值对 (Key-Value Pair)**的形式：
  - Variable Name（变量名）: 你给这个信息起的名字，比如 myApiKey, authToken, apiUsername, apiPassword。
  - Value（值）: 对应的真实信息，
    - 比如你的 API Key 字符串 abc123xyz，
    - 你的 Bearer TokeneyJ…，
    - 你的用户名 testuser，
    - 你的密码 secretpass。
- 重要：
  - 对于密码、Client Secret 这种极其敏感的信息，可以点击值输入框旁边的小锁🔒或眼睛图标，将其标记为 “Secret”（秘密）。这样它在界面上会显示为星号 ******，更加安全。
在 Auth 配置中使用变量：
1. 回到你的请求或集合的 Auth 标签页。在需要填入敏感信息的地方
  1. 比如 Basic Auth 的 Password 字段，
  2. Bearer Token 的 Token 字段，
  3. API Key 的 Value 字段，
  4. OAuth 2.0 的 Client Secret 字段），不要直接填写真实的值，而是使用 {{变量名}} 的语法。例如：
    - Password: {{apiPassword}}
    - Token: {{authToken}}
    - API Key Value: {{myApiKey}}
    - Client Secret: {{apiClientSecret}}
激活环境：
1. 在 Bruno 主界面顶部的环境下拉菜单中，选择你刚刚配置好的环境（比如 Development）。
运行请求：
1. 现在当你运行请求时，Bruno 会自动查找 {{变量名}}，并从你当前激活的环境中取出对应的真实值来使用。

4.2- 环境变量的好处

超级安全：
- 真实密钥只存在环境变量里，不会暴露在请求配置中。你可以安全地分享你的 Bruno 集合（只要不分享环境文件）。
超级方便：
- 要切换到生产环境？只需在下拉菜单中选择 Production 环境（假设你已为 Production 环境设置了对应的变量值），所有请求的认证信息自动切换！
超级易维护：
- API Key 过期了？只需在环境变量里更新一次值，所有使用该变量的地方都自动生效！

5- 第五部分：最重要的规则 - 阅读 API 文档

Bruno 是一个强大的工具，它提供了配置各种身份验证方式的界面。但是，
- 具体应该用哪种方式、
- 用户名/密码是什么、
- Token 从哪里来、
- API Key 放 Header 还是 Query、
- OAuth 2.0 的那些 URL 和 ID 是多少……所有这些问题的答案，都不在 Bruno 里，而是在你要调用的那个 API 的官方文档里！

在你开始在 Bruno 中配置 Auth 之前，请务必打开该 API 的开发者文档，找到关于 “Authentication”（身份验证）或 “Authorization”（授权）的章节，仔细阅读以下信息：

需要哪种认证类型？
- （Basic, Bearer, API Key, OAuth 2.0, etc.）
如何获取凭证？
- 是注册后自动获得？
- 需要调用某个登录 API 获取 Token？
- 需要在开发者后台创建应用获取 Key 和 Secret?)
凭证的具体细节：
- Basic Auth:
  - 用户名和密码是什么？
- Bearer Token:
  - 如何生成或获取这个 Token？Token 的有效期是多久？
- API Key:
  - Key 的名称是什么？
  - 应该放在 Header 还是 Query Param？
- OAuth 2.0: Grant Type 是什么？
  - Auth URL, Token URL, Client ID, Client Secret, Scope 分别是什么？
  - Callback URL 应该怎么设置？

6- 第六部分：练练手吧

打开 Bruno，创建一个新的空集合，比如叫 “Auth Practice”。
在集合里创建一个请求，随便用一个公开的测试 API 地址，比如 https://httpbin.org/get（这个不需要认证）。
熟悉界面：
- 在集合层面（点击集合旁边的…->Settings->Auth），尝试选择 Basic Auth，随便填入 user/pass。
- 回到你的请求，打开 Auth 标签页。你会看到它默认显示继承自集合的 Basic Auth。
- 在请求层面，尝试从下拉菜单选择 Bearer Token，随便填入 my_test_token。你会看到它覆盖了集合的设置。
- 再尝试选择 None（No Auth）。
- 再改回 Inherit Auth from Collection，看看它是否又变回了 Basic Auth。
练习变量：
- 去环境管理（眼睛图标），创建一个叫 TestEnv 的环境。
- 在 TestEnv 里添加一个变量 test_token，值为 real_bearer_token_123，并将其设为 Secret。
- 回到请求的 Auth 标签页，选择 Bearer Token。在 Token 输入框里，输入 {{test_token}}。
- 确保顶部的环境下拉菜单选择了 TestEnv。
- （虽然 httpbin.org/get 不需要认证，但这个练习能帮你熟悉变量的使用流程）。

希望这份超级详细的教程能让你对 Bruno 的身份验证功能有一个清晰的认识！记住，核心是理解层级与继承，熟悉各种认证类型的配置项，养成使用环境变量的好习惯，以及最重要的——仔细阅读 API 文档。

#开发工具 #API测试

#API #教程 #Bruno #身份验证 #认证 #入门

Obsidian加Cursor就是最强AI知识库上一篇

2025年免费API清单下一篇