📚 课程目录第4章 API认证与授权机制

API 认证与授权机制

聊到 SDK 设计，认证和授权是绕不开的门槛。你想想看，一个 SDK 要是连调用者是谁都搞不清，谁敢把核心接口开放出去？我记得刚做第一个开放平台 SDK 时，就因为认证握手没处理好，线上出了好几次安全漏洞。嗯，从那以后，我习惯把认证和授权放到架构设计的第一优先级来考虑。

常见的 API 认证方式

说白了，认证就是「证明你是你」。SDK 场景下，我见过的主流方式就这么几种：

认证方式	核心原理	适用场景	安全级别
	明文传输一个固定的密钥	内部服务、低敏感度接口	低
Basic Auth	用户名+密码 Base64 编码	兼容旧系统、快速验证	低（需配合 HTTPS）
OAuth 2.0	授权码/客户端凭证/隐式/密码模式	第三方接入、移动端、跨平台	高
JWT (自包含 )	Header.Payload.Signature 三段式	无状态认证、分布式系统	中高
HMAC 签名	密钥 + 请求参数哈希	防篡改、数据完整性校验	高

我的个人习惯： 对外 SDK 推荐 OAuth 2.0 的客户端凭证模式（client_credentials），配合简短有效的 access 。对内微服务间调用，用 HMAC 签名更轻量，也更容易 debug。

深入 JWT：为什么它这么流行？

JWT 这几年几乎成了 API 认证的标配。原因很简单——无状态。服务器不用存 session，只需验证签名。我在项目中遇到过不少团队，直接把用户 ID、过期时间怼到 payload 里就往客户端发，结果签名算法用 none，被白帽子直接秒破。

正确的 JWT 结构长这样：

// Header
{
  "alg": "HS256",
  "typ": "JWT"
}
// Payload
{
  "sub": "user_12345",
  "role": "admin",
  "iat": 1700000000,
  "exp": 1700003600
}
// Signature
HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret
)

我曾经踩过的坑： 有一次把 JWT 的过期时间设成了 7 天，结果测试环境泄露后，攻击者直接拿它调了一周的生产接口。现在我的铁律是：access 最多 30 分钟，refresh 放服务端内存或安全存储，走短生命周期。

授权模型：谁来做什么事

认证通过后，下一步就是授权——「你能干什么」。我在架构里常用两种模型对比：

RBAC（基于角色）：角色绑定权限，用户绑定角色。适合组织结构稳定的企业系统。比如：管理员可删除，编辑者可修改，查看者只能读。
ABAC（基于属性）：根据用户、资源、环境等属性动态决策。比如：只允许本部门的员工在上班时间查看本部门的文档。灵活但规则复杂，性能开销大。

做 SDK 时，我建议优先用 RBAC。为什么呢？因为 SDK 的接口粒度通常较粗，RBAC 的决策逻辑能缓存，性能好维护。ABAC 放在上层业务逻辑里更合适。

缓存策略：别让认证成为性能瓶颈

每次请求都去数据库查权限表？那你的 SDK 肯定扛不住。我在设计缓存层时，有这三条原则：

缓存：解析后的 access 信息（用户 ID、角色、过期时间）用本地内存缓存（如 Guava Cache 或 Caffeine），TTL 设为剩余时间的一半。
权限缓存：RBAC 的角色-权限映射表，缓存到 Redis，设置 5 分钟自动失效。一旦权限变更，手动淘汰缓存。
限流缓存：对同一个做计数器，用 Redis + Lua 脚本实现原子递增，防止重复请求穿透到后端。

// 伪代码： 缓存策略
public class TokenCache {
    private Cache<String, TokenInfo> cache = Caffeine.newBuilder()
        .expireAfterWrite(15, TimeUnit.MINUTES)
        .maximumSize(10000)
        .build();

    public TokenInfo get(String ) {
        return cache.get(, k -> {
            // 只有缓存未命中时才解析 JWT/查 DB
            return parseTokenFromDB(k);
        });
    }
}

  关键点： 缓存一定要设置合理的 TTL，并预留手动清理接口。否则线上改完权限，用户还得等缓存过期才能生效，那就是生产事故。

一张图看懂 API 认证授权流程

我把上述各种认证方式的通用流程画了出来。不同颜色代表不同认证路径，但核心都是「客户端 - 认证服务 - 资源服务」三角关系：

特别提醒： 图中缓存层一定要做「缓存穿透保护」。我遇到过一种情况——恶意请求使用大量不同的伪造，每次都会穿透缓存打到数据库，数据库瞬间崩溃。解决方案是缓存空结果+布隆过滤器，从源头拦截无效。

避坑指南：这些我全踩过

泄露于日志：有一次排查线上问题，我把请求参数打了全量日志，结果 access 明文记录在 ELK 里。后来我们强制对字段做 MaskLogFilter，只显示前 4 位和末 4 位。
时间同步问题：JWT 的 iat 和 exp 依赖服务器时间。如果认证服务和资源服务时间偏差超过 30 秒，就会提前失效。建议用 NTP 同步，并在校验时允许 30 秒的 leeway。
权限缓存与 realtime 冲突：某次紧急权限回收后，管理员改了角色绑定的权限，但缓存 TTL 还剩 4 分钟。这 4 分钟内被攻击者利用，造成了数据删除。此后我们做了权限变更的 websocket 广播，强制淘汰所有相关缓存。

好了，认证与授权这块就先讲这么多。记住：没有安全的系统，只有不断迭代的防护意识。把认证流程和缓存策略设计得足够健壮，你的 SDK 才能在上线后睡得踏实。