Bruno 身份验证新手入门教程

1. Bruno 身份验证新手入门教程

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

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

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

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

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

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

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

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

3.1. 最高层级：集合 (Collection)

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

3.2. 中间层级：文件夹 (Folder)

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

3.3. 最具体层级：请求 (Request)

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

3.4. 核心：继承 (Inheritance)

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

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

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

4.1. 无认证 (No Auth / None)

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

4.2. 基本认证 (Basic Auth)

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

4.3. 承载令牌 (Bearer Token)

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

4.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，值为你的 Key abc123xyz。
- 那么你在 Bruno 里就填：Key = X-My-ApiKey、Value = abc123xyz、Add to = Header。

4.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 的文档。每个服务的配置细节都可能不同。耐心阅读文档是必须的！

4.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 的文档。
如何配置：
- 选择对应的类型，然后根据界面提示和你从服务商文档获取的信息填写。

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

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

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

5.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 Token eyJ…，
    - 你的用户名 testuser，
    - 你的密码 secretpass。
  - 重要：
    - 对于密码、Client Secret 这种极其敏感的信息，可以点击值输入框旁边的小锁🔒或眼睛图标，将其标记为 “Secret”（秘密）。这样它在界面上会显示为星号 ******，更加安全。
在 Auth 配置中使用变量：
1. 回到你的请求或集合的 Auth 标签页。在需要填入敏感信息的地方（比如 Basic Auth 的 Password 字段、Bearer Token 的 Token 字段、API Key 的 Value 字段、OAuth 2.0 的 Client Secret 字段），不要直接填写真实的值，而是使用 {{变量名}} 的语法。例如：
  - Password：{{apiPassword}}
  - Token：{{authToken}}
  - API Key Value：{{myApiKey}}
  - Client Secret：{{apiClientSecret}}
激活环境：
1. 在 Bruno 主界面顶部的环境下拉菜单中，选择你刚刚配置好的环境（比如 Development）。
运行请求：
1. 现在当你运行请求时，Bruno 会自动查找 {{变量名}}，并从你当前激活的环境中取出对应的真实值来使用。

5.2. 环境变量的好处

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

6. 第五部分：最重要的规则 - 阅读 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 等）
如何获取凭证？
- 是注册后自动获得？
- 需要调用某个登录 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 应该怎么设置？

7. 第六部分：练练手吧

打开 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 文档。

#AI #API测试 #开发工具

#AI #开发工具 #Bruno #API测试 #身份验证

Auth0 上一篇

AutoI18n - One click update NextJs project i18n 下一篇