api-auth-patterns

API 认证的指导原则与最佳实践（JWT、Bearer 密钥）以及常见 API 通信模式（REST、GraphQL、gRPC、WebSockets、Webhooks、MCP） 1. API 认证：指导原则与最佳实践 1.1 JWT（JSON Web Token） - 使用标准库生成和验证 JWT，避免自行实现加密逻辑。 - 设置合理的过期时间（exp），避免令牌长期有效。 - 使用强签名算法（如 HS256 或 RS256），推荐使用非对称加密（RS256）以增强安全性。 - 不要在 JWT 中存储敏感信息（如密码、个人身份信息），因其可被解码。 - 实施令牌刷新机制，使用短期访问令牌配合长期刷新令牌。 - 验证令牌的发行者（iss）、受众（aud）和签名，防止伪造。 1.2 Bearer 密钥（API Keys） - 将 API 密钥通过 Authorization 头传递，格式为：Authorization: Bearer <token>。 - 为每个客户端或服务分配唯一密钥，便于审计和撤销。 - 定期轮换密钥，降低泄露风险。 - 限制密钥权限，遵循最小权限原则。 - 不要在 URL 或日志中暴露 API 密钥。 - 使用 HTTPS 传输，防止中间人攻击。 1.3 通用安全建议 - 始终使用 HTTPS 加密通信。 - 实施速率限制和防滥用机制。 - 记录认证失败尝试，用于监控和异常检测。 - 支持多因素认证（MFA）以增强关键操作的安全性。 2. 常见 API 通信模式 2.1 REST（Representational State Transfer） - 基于 HTTP 方法（GET、POST、PUT、DELETE）操作资源。 - 使用标准状态码（如 200、201、400、401、404、500）表示结果。 - 资源以 URL 路径表示（如 /users/123）。 - 支持 JSON 或 XML 数据格式，推荐 JSON。 - 无状态设计，每次请求包含完整上下文。 - 适合 CRUD 操作和公开 Web API。 2.2 GraphQL - 客户端可精确指定所需数据，减少过度获取或不足获取。 - 单一端点处理所有请求（通常为 /graphql）。 - 强类型系统，支持自省和文档生成。 - 支持查询（Query）、变更（Mutation）和订阅（Subscription）。 - 适合复杂数据关系和前端驱动的数据需求。 - 需注意查询深度和复杂度控制，防止资源耗尽。 2.3 gRPC - 基于 HTTP/2 的高性能 RPC 框架。 - 使用 Protocol Buffers（protobuf）定义服务和消息结构。 - 支持双向流、客户端流、服务端流和单向调用。 - 强类型接口，自动生成客户端和服务端代码。 - 适合微服务间高效通信，尤其在内部系统中。 - 需处理跨语言兼容性和版本管理。 2.4 WebSockets - 提供全双工、持久化连接，支持实时双向通信。 - 适用于聊天、通知、实时协作等场景。 - 建立连接后通过消息帧进行数据交换。 - 需处理连接断开重连、心跳机制和消息顺序。 - 注意资源消耗和扩展性设计。 2.5 Webhooks - 事件驱动机制，服务端在特定事件发生时向客户端推送数据。 - 客户端需提供可公开访问的回调 URL。 - 使用 HTTPS 确保安全性，建议验证签名或 HMAC。 - 实现幂等性处理，应对重复推送。 - 提供重试机制和失败日志，保障可靠性。 - 适合支付通知、状态更新等异步事件。 2.6 MCP（Model Context Protocol，模型上下文协议） - 用于 AI 模型与外部工具或数据源交互的协议。 - 定义标准化的接口，使模型能调用函数、获取上下文或执行操作。 - 强调安全性，限制模型可访问的资源范围。 - 支持动态工具注册和上下文管理。 - 适用于 AI 应用集成外部系统（如数据库、API、文件系统）。 - 需设计清晰的权限控制和审计日志。 总结： 选择合适的认证方式和通信模式应根据具体应用场景、性能需求和安全要求综合评估。无论采用何种技术，都应遵循最小权限、数据加密、输入验证和日志监控等安全基本原则。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本