API 认证方法对比：API 密钥、JWT、OAuth2 与基本认证

API 认证方法：实用对比

选择合适的认证机制会影响安全性、开发者体验和运维复杂度。

基本认证（Basic Authentication）

在每个请求头中发送 base64 编码的 username:password。

Authorization: Basic dXNlcjpwYXNzd29yZA==

优点： 极其简单，普遍支持，内置于每个 HTTP 客户端。 缺点： 每个请求都携带凭证，无过期时间，base64 不是加密（需要 HTTPS）。 适用场景： 内部工具、CLI 脚本、遗留系统兼容。切勿用于面向用户的 API。

API 密钥（API Keys）

为每个客户端颁发的静态令牌。

// 客户端
fetch(url, { headers: { 'X-API-Key': process.env.API_KEY } });

// 服务端：验证哈希后的密钥
const hash = crypto.createHash('sha256').update(key).digest('hex');
const client = await db.query('SELECT * FROM api_keys WHERE hash = $1', [hash]);

安全实践： 仅存储 SHA-256 哈希，按环境添加前缀（sk_live_、sk_test_），允许自行轮换，为每个密钥设置速率限制。

优点： 简单、无状态、对开发者友好。 缺点： 无内置过期时间，作用域粒度有限。 适用场景： 机器对机器、公开的开发者 API（Stripe/SendGrid 模式）。

JWT（JSON Web Tokens）

包含签名声明的自包含令牌。服务端验证签名——无需数据库查询。

// 登录时签发
const token = jwt.sign(
  { sub: user.id, email: user.email, role: user.role },
  process.env.JWT_SECRET,
  { algorithm: 'HS256', expiresIn: '15m' }
);

// 验证
req.user = jwt.verify(token, process.env.JWT_SECRET, { algorithms: ['HS256'] });

优点： 无状态（水平扩展），包含用户数据，设计为短生命周期。 缺点： 过期前无法撤销——保持访问令牌短时效（5-15 分钟），使用刷新令牌。 适用场景： SPA、移动应用、微服务中的用户认证。

OAuth 2.0

授权框架——用户授权第三方应用访问，无需共享凭证。

1. 用户点击“使用 GitHub 登录”
2. 应用重定向到 GitHub 的授权端点
3. 用户批准请求的作用域
4. GitHub 重定向回应用，附带授权码
5. 应用用授权码交换访问令牌
6. 应用使用令牌代表用户调用 GitHub API

应使用的授权类型： Authorization Code + PKCE（Web/移动端），Client Credentials（服务端到服务端）。 避免已弃用的： Implicit grant、Resource Owner Password grant。

优点： 行业标准，作用域权限，用户可以撤销访问。 缺点： 正确实现复杂，重定向流程增加用户体验摩擦。 适用场景： “使用 Google/GitHub 登录”、第三方应用集成。

HMAC 签名（HMAC Signatures）

对请求体和时间戳进行签名——密钥永不传输。

function signRequest(method, path, body, secret) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const payload = [method, path, timestamp, body].join('\n');
  const sig = crypto.createHmac('sha256', secret).update(payload).digest('base64');
  return { 'X-Timestamp': timestamp, 'X-Signature': `hmac-sha256=${sig}` };
}
// 防止重放攻击：如果 |timestamp - now| > 300 秒则拒绝

适用场景： Webhook 验证、金融 API、需要防篡改请求的场景。

对比

→ 使用 JWT 解析器 解码和检查 JWT 令牌。