API 安全设计原则

一、引言

随着微服务架构、前后端分离和移动端应用的全面普及，API（Application Programming Interface）已成为现代应用的核心通信载体。从 Web 前端到移动 App，从内部服务调用到第三方开放平台，API 的覆盖面持续扩大。与此同时，API 安全问题也日益突出——OWASP 自 2019 年起专门发布 API Security Top 10，将 API 安全从 Web 安全中单独提炼，足见其重要性。

API 安全的设计不应是上线前的"安全检查清单"，而应贯穿于系统架构设计、编码实现、测试验证和运营监控的全生命周期。本文围绕 API 安全的六大核心领域——认证（Authentication）、授权（Authorization）、限流（Rate Limiting）、审计（Audit Logging）、敏感数据保护（Sensitive Data Protection） 以及 安全架构原则——进行系统阐述，为后端开发工程师和架构师提供可落地的设计参考。

二、API 安全整体架构与设计原则

2.1 纵深防御架构

API 安全应采用纵深防御（Defense in Depth） 的架构理念，在网络层、传输层、应用层、数据层分别部署安全控制措施，形成多层防护体系：

层级	安全措施	说明
网络层	WAF、DDoS 清洗、IP 黑白名单	抵御网络层攻击和流量清洗
传输层	TLS 加密、mTLS 双向认证	保证数据在传输过程中的机密性和完整性
应用层	认证、授权、输入校验、限流	核心业务安全逻辑
数据层	存储加密、脱敏、访问控制	保护持久化数据安全

2.2 安全设计核心原则

在 API 的安全设计中，应遵循以下基本原则：

（1）最小权限原则（Principle of Least Privilege）

每个 API 调用方（用户、服务、客户端）仅应获得完成其职责所需的最小权限集合。默认拒绝所有未显式授权的访问，而非默认放行再拦截。

（2）默认安全（Secure by Default）

API 的默认配置应当是安全的——例如默认要求认证、默认启用 HTTPS、默认对输出数据进行编码/脱敏。安全不应该是可选项。

（3）永不信任用户输入（Never Trust User Input）

所有来自客户端的数据——包括请求头、查询参数、请求体、Cookie、文件上传——都必须经过严格的校验、清洗和转义。输入校验应采用白名单（允许列表）优先的原则。

（4）失败安全（Fail Secure）

当安全组件发生故障或抛出异常时，系统应默认拒绝访问，而非放行。例如，权限校验服务超时时应返回 403 Forbidden，而非 200 OK。

（5）显式声明安全边界（Explicit Security Boundaries）

在架构文档和代码中清晰标出信任边界（Trust Boundary），明确哪些区域是受信区域、哪些是不可信区域。每个跨越信任边界的数据流都应经过安全检查。

（6）可审计性（Accountability）

所有敏感操作和安全管理事件必须记录到审计日志中，确保可以追溯至具体调用方、时间、操作内容和结果，从而支持事后的安全审查和取证。

三、认证（Authentication）

认证是 API 安全的第一道防线，其核心是回答"你是谁？"的问题。在 API 场景中，常见的认证方式包括 API Key、JWT、OAuth2 和 Session 认证。

3.1 API Key

API Key 是最简单、最直接的 API 认证方式。服务端为每个调用方生成一个唯一的密钥字符串，调用方在请求中通过 Header（如 X-API-Key）、查询参数或 Cookie 携带该密钥，服务端校验其合法性。

优点：

实现简单，无需复杂的握手流程
适合服务间调用、SDK/客户端库认证

缺点：

密钥静态不变，泄露后风险极高
缺乏过期机制（除非手动轮换）
难以实现细粒度的权限控制
不适合用户级别的认证场景

最佳实践：

API Key 应通过安全的渠道（如门户后台、加密邮件）分发
启用定期轮换策略，支持多 Key 并行生效以平滑过渡
API Key 不应出现在 URL 查询参数中（避免被日志或 Referer 泄露）
配合 IP 白名单使用，增加一层安全约束

3.2 JWT（JSON Web Token）

JWT 是一种自包含（Self-contained）的令牌格式，由 Header、Payload、Signature 三部分组成，经过 Base64URL 编码后以 . 连接。服务端使用密钥对令牌进行签名，客户端在后续请求中携带该令牌，服务端验证签名即可确认令牌的合法性和完整性。

优点：

无状态（Stateless），服务端无需维护 Session 存储
结构标准化（RFC 7519），具有广泛的生态支持
可在 Payload 中携带用户身份和权限声明
适合分布式系统和微服务架构

缺点：

令牌签发后无法主动撤销（需配合黑名单或短过期时间）
Payload 仅经 Base64URL 编码而非加密，敏感信息不应放入 Payload
令牌体积较大，可能导致 HTTP Header 膨胀

最佳实践：

使用强签名算法（推荐 RS256 或 ES256，避免使用 HS256 这类对称算法在跨服务场景中的密钥分发问题）
设置合理的过期时间（Access Token 建议 15-30 分钟，Refresh Token 建议 7-30 天）
不在 Payload 中存放敏感信息（密码、手机号、身份证等）
启用 jti（JWT ID）声明，结合黑名单机制实现令牌撤销
使用 HTTPS 传输，防止令牌被中间人截获

3.3 OAuth2

OAuth2 是一个授权框架，但在实际使用中常被用作认证的基础。它定义了四种授权模式（Authorization Grant）：授权码模式（Authorization Code）、隐式模式（Implicit）、密码模式（Resource Owner Password Credentials）和客户端凭证模式（Client Credentials）。

授权码模式流程（最推荐）：

客户端引导用户前往授权服务器
用户认证并授权后，授权服务器返回授权码
客户端用授权码向授权服务器换取 Access Token
客户端使用 Access Token 访问资源服务器

优点：

授权与认证分离，支持第三方应用安全访问用户资源
支持多种授权流程，灵活适配不同场景
令牌支持分类（Access Token、Refresh Token）和作用域（Scope）

缺点：

协议相对复杂，实现成本较高
需要维护授权服务器和资源服务器
流程不当时容易引入安全漏洞（如回调 URL 未校验）

最佳实践：

始终使用授权码模式 + PKCE（Proof Key for Code Exchange），避免授权码拦截攻击
严格校验 redirect_uri，防止开放重定向漏洞
Access Token 使用 JWT 格式，方便资源服务器直接验证
使用 Scope 机制实现最小权限授予

3.4 Session 认证

传统的 Session 认证通过在服务端维护 Session 对象、客户端通过 Cookie 携带 Session ID 来标识用户身份。

优点：

服务端完全掌控 Session 生命周期，可随时撤销
生态成熟，框架支持完善（如 Spring Session、Express Session）

缺点：

有状态，在分布式环境中需引入共享存储（如 Redis）
Session ID 固定后易受会话固定（Session Fixation）攻击
对移动端和跨域场景不友好

最佳实践：

分布式环境下使用 Redis 或 Memcached 集中存储 Session
启用 Cookie 的 HttpOnly、Secure、SameSite 属性
登录成功后重新生成 Session ID，防止会话固定攻击

3.5 认证方式选型对比

维度	API Key	JWT	OAuth2	Session
状态	无状态	无状态	无状态	有状态
适用场景	服务间调用、SDK	微服务、前后端分离	第三方授权、开放平台	传统 Web 应用
撤销能力	弱（需黑名单）	弱（需黑名单）	中等（令牌吊销）	强（删除 Session）
复杂度	低	中	高	中
安全风险	Key 泄露	签名算法、Payload 敏感信息	重定向、CSRF	会话固定、XSS
推荐度	⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐

四、授权（Authorization）

认证确认了"你是谁"，授权则回答**"你能做什么"**。在 API 设计中，授权决定了经过认证的调用方是否可以执行特定操作或访问特定资源。

4.1 RBAC（Role-Based Access Control）

RBAC 是目前应用最广泛的授权模型，其核心思想是将权限授予角色，再将角色授予用户，实现用户与权限的解耦。

核心概念：

用户（User）：系统的调用方
角色（Role）：权限的逻辑集合（如管理员、运营人员、普通用户）
权限（Permission）：对特定资源的操作许可（如 article:create、article:delete）
会话（Session）：用户激活的角色映射

在 API 中的实现：

yaml

# 权限定义示例
permissions:
  - article:create
  - article:read
  - article:update
  - article:delete
  - user:manage

# 角色-权限映射
roles:
  admin: [article:create, article:read, article:update, article:delete, user:manage]
  editor: [article:create, article:read, article:update]
  viewer: [article:read]

优点：

模型简单直观，易于理解和维护
权限管理集中化，变更成本低
符合大多数业务场景需求

缺点：

角色颗粒度较粗，难以处理"例外"权限
角色数量膨胀后管理复杂度上升（角色爆炸）

4.2 ABAC（Attribute-Based Access Control）

ABAC 基于属性进行动态授权决策，不再依赖固定的角色层次。支持的属性维度包括：

主体属性（Subject Attributes）：用户 ID、部门、职级、安全等级
资源属性（Resource Attributes）：资源类型、所属部门、敏感级别
环境属性（Environment Attributes）：访问时间、IP 地址、地理位置、设备类型
操作属性（Action Attributes）：操作类型（读/写/删除）

策略引擎示例（类 XACML 风格）：

Rule: 仅允许本部门员工在工作时间（9:00-18:00）查看本部门文档
  IF subject.department == resource.department
     AND environment.time >= 09:00
     AND environment.time <= 18:00
  THEN PERMIT

优点：

授权颗粒度极细，支持复杂业务规则
动态决策，无需预先固定角色映射
适合多租户、数据隔离严格的场景

缺点：

策略引擎复杂度高，实现成本大
策略数量增长后可能引入性能瓶颈
调试和排错困难

4.3 ACL（Access Control List）

ACL 是最传统的授权模型，为每个资源维护一个访问列表，记录哪些主体对该资源拥有哪些权限。

在 API 中的表现：

文件系统中的 rwx 权限是 ACL 的经典案例
在 REST API 中，可表现为资源层面的用户-权限映射表

优点：

模型直观，易于理解和调试
支持细粒度的"例外"授权

缺点：

资源数量增长后列表维护成本极高
不便于查看某个用户对所有资源的权限总览
现代 API 场景中已较少单独使用

4.4 选型建议

场景	推荐模型	原因
内部管理系统、后台	RBAC	角色清晰，管理简便
多租户 SaaS 平台	RBAC + ABAC 混合	RBAC 管理基础角色，ABAC 处理租户隔离
开放 API 平台	RBAC + Scope	利用 Scope（OAuth2）实现细粒度操作授权
金融、医疗等高合规场景	ABAC	需要基于多维度属性进行动态决策
简单资源分享	ACL	用户少、资源少时简单直接

五、限流（Rate Limiting）

限流是 API 可用性保护的核心手段，防止单一方过度消耗服务资源，保障所有调用方的公平使用。

5.1 限流算法

5.1.1 令牌桶算法（Token Bucket）

令牌桶以固定速率向桶中添加令牌，每个请求从桶中取出一个令牌，桶满则令牌溢出丢弃。

特点：

允许一定的突发流量（桶中积累的令牌可被瞬间消费）
平均速率稳定可控
适合允许突发请求的 API 场景

java

// 令牌桶伪代码
public class TokenBucket {
    private final long capacity;        // 桶容量
    private final long refillRate;      // 令牌补充速率（个/秒）
    private long tokens;                // 当前令牌数
    private long lastRefillTimestamp;   // 上次补充时间

    public synchronized boolean allowRequest() {
        refill();
        if (tokens > 0) {
            tokens--;
            return true;
        }
        return false;
    }

    private void refill() {
        long now = System.currentTimeMillis();
        long elapsed = now - lastRefillTimestamp;
        long newTokens = elapsed * refillRate / 1000;
        tokens = Math.min(capacity, tokens + newTokens);
        lastRefillTimestamp = now;
    }
}

5.1.2 漏桶算法（Leaky Bucket）

漏桶将请求视为水滴，以固定速率从桶底流出。桶容量固定，桶满则新请求被丢弃。

特点：

输出速率完全固定，无突发
适用于需要平滑流量的场景（如数据库写入、第三方 API 调用）
对突发请求不友好，可能导致请求大量排队超时

5.1.3 滑动窗口算法（Sliding Window）

滑动窗口将时间划分为多个小片段（如 1 秒为粒度），记录每个片段内的请求计数，滑动统计最近一个完整窗口内的总请求数。

特点：

解决了固定窗口算法的"边界突刺"问题
精度受窗口片段大小影响，片段越小精度越高但存储开销越大
适合需要精确控制的场景

时间轴：0s    1s    2s    3s    4s    5s
窗口  [=====]                          ← 0-1s 窗口
        [=====]                        ← 1-2s 窗口（滑动）
              [=====]                  ← 2-3s 窗口（滑动）

5.2 分布式限流（Redis 实现）

在分布式环境中，单机限流无法跨节点协调，需要引入集中式的限流计数器。Redis 基于其高性能和原子性操作，成为分布式限流的首选方案。

基于 Redis + Lua 脚本的滑动窗口限流：

lua

-- Lua 脚本：滑动窗口限流
local key = KEYS[1]                 -- 限流 Key
local window = tonumber(ARGV[1])    -- 窗口大小（毫秒）
local limit = tonumber(ARGV[2])     -- 窗口内最大请求数
local now = tonumber(ARGV[3])       -- 当前时间戳

-- 移除窗口外的旧记录
redis.call('ZREMRANGEBYSCORE', key, 0, now - window)

-- 统计当前窗口内的请求数
local count = redis.call('ZCARD', key)

if count < limit then
    -- 添加当前请求记录
    redis.call('ZADD', key, now, now .. ':' .. math.random())
    redis.call('EXPIRE', key, window / 1000 + 1)
    return 1  -- 允许请求
else
    return 0  -- 拒绝请求
end

5.3 各层限流策略

层级	限流粒度	实现方式	说明
网络层	IP	WAF、防火墙、iptables	防御 DDoS 和爬虫
网关层	客户端/API Key/路由	网关限流插件（Kong、APISIX、Spring Cloud Gateway）	统一入口限流
应用层	用户/接口/方法	框架拦截器或注解（如 Spring `@RateLimiter`）	业务级精细限流
数据层	数据源/连接池	连接池配置、数据库并发控制	保护后端存储

推荐的多层限流配置示例：

网关层：每 API Key 1000 请求/分钟
应用层：每用户 100 请求/分钟
应用层：每接口 500 请求/分钟
数据层：每服务 2000 数据库查询/分钟

5.4 限流响应策略

当请求被限流拒绝时，服务端应返回标准的 HTTP 状态码和响应头，帮助调用方理解限流状态并自适应调整：

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623456789

六、审计（Audit Logging）

审计日志旨在记录 API 系统中的关键事件，为安全事件溯源、合规审查和运营分析提供可靠的数据基础。

6.1 审计范围的界定

并非所有 API 请求都需要记录到审计日志，否则日志量将过大且关键信息被淹没。应重点关注以下类别的请求：

（1）敏感数据访问

涉及个人身份信息（PII）的数据查询
财务数据、医疗记录、法律文件访问

（2）敏感操作

用户创建、删除、权限变更
数据删除或批量导出
密钥生成、轮换或吊销
系统配置变更（限流阈值、白名单修改等）

（3）安全事件

认证失败（特别是短时间内连续失败）
授权拒绝（403 频繁出现）
请求参数校验失败（可能是攻击尝试）

6.2 审计日志结构

建议采用结构化的日志格式（如 JSON），便于后续的采集、分析和检索。每条审计日志应包含以下字段：

json

{
  "version": "1.0",
  "timestamp": "2026-07-16T10:30:00.000+08:00",
  "event_id": "a8f3c1e2-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "event_type": "USER_PERMISSION_CHANGE",
  "severity": "HIGH",
  "source": {
    "ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0 ...",
    "service_name": "user-service",
    "request_id": "req_abc123"
  },
  "actor": {
    "user_id": "u_10086",
    "username": "zhangsan",
    "role": "admin"
  },
  "action": {
    "method": "POST",
    "path": "/api/v2/users/u_10010/permissions",
    "resource": "user:permission",
    "operation": "grant_role",
    "parameters": {
      "target_user": "u_10010",
      "role": "editor"
    }
  },
  "result": {
    "status_code": 200,
    "success": true
  },
  "context": {
    "trace_id": "trace_7f8a9b0c",
    "span_id": "span_3d4e5f6a"
  }
}

6.3 审计日志存储

审计日志的存储需要考虑写入性能、存储成本和查询效率的平衡：

存储方案	适用场景	优点	缺点
数据库（MySQL/PostgreSQL）	小规模、需要复杂查询	结构化、支持 SQL	写入性能有限，存储成本高
时序数据库（Elasticsearch/OpenSearch）	中等规模、全文检索	全文搜索、聚合分析	运维复杂度较高
对象存储（S3/MinIO）+ 索引	大规模日志归档	成本低、长期保存	实时查询能力弱
日志服务（阿里云 SLS/腾讯云 CLS）	云原生场景	托管免运维、自带分析	供应商锁定

最佳实践：

审计日志应只追加（Append-Only），不允许修改和删除
设置合理的日志保存周期（建议至少 180 天，合规要求严格时建议 1 年以上）
关键审计日志应进行数字签名，防止篡改
落实日志的访问控制，审计日志本身也是敏感数据

七、敏感数据保护

API 在传输和存储过程中会涉及大量的敏感数据，包括但不限于：用户密码、手机号、身份证号、银行卡号、密钥材料、业务敏感字段等。对这些数据的保护应贯穿数据的全生命周期。

7.1 传输加密（TLS）

所有 API 接口必须强制使用 TLS 1.2 或更高版本
禁用 TLS 1.0/1.1 和 SSL 2.0/3.0 等已不安全的协议
配置强密码套件（Cipher Suite），优先使用 ECDHE + AES-GCM 套件
启用 HSTS（HTTP Strict Transport Security），防止降级攻击
对于服务间调用，推荐使用 mTLS（双向 TLS）进行身份验证和加密通信

7.2 存储加密

层级	加密方式	说明
全盘加密	BitLocker/LUKS	防止物理磁盘被窃取后数据泄露
数据库 TDE	Transparent Data Encryption	透明加密数据文件
字段级加密	AES-256-GCM	对敏感字段单独加密
密钥管理	KMS/HSM	加密密钥由专用服务管理

密码存储规范（铁律）：

绝不允许明文存储密码
使用带盐（Salt）的慢哈希算法，推荐 bcrypt（cost >= 10）、Argon2id 或 scrypt
禁止使用 MD5、SHA-1 等快速哈希算法存储密码

7.3 数据脱敏

数据脱敏发生在 API 的响应返回阶段，确保敏感信息不会完整暴露给非授权调用方。

常见脱敏规则：

数据类型	原始值	脱敏后	规则
手机号	13812345678	138****5678	保留前 3 后 4
身份证号	110101199001011234	110101******1234	保留前 6 后 4
银行卡号	6222021234567890	622202******7890	保留前 6 后 4
邮箱	zhangsan@example.com	z****n@example.com	用户名部分脱敏
IP 地址	192.168.1.100	192.168..	隐藏后两段

java

// 手机号脱敏示例
public static String maskPhone(String phone) {
    if (phone == null || phone.length() != 11) {
        return phone;
    }
    return phone.replaceAll("(\\d{3})\\d{4}(\\d{4})", "$1****$2");
}

7.4 掩码显示与前端保护

除了后端脱敏，前端展示层也应实施安全控制：

敏感字段默认使用掩码显示，用户主动点击"查看"后临时明文展示
明文展示时记录审计日志，且设置 5-10 秒自动回弹为掩码
禁止前端控制台打印敏感信息
禁止敏感信息出现在 URL 查询参数、Referer 和浏览器历史记录中

八、原则总结

下表汇总了本文讨论的六大安全领域的设计原则和关键要点，可作为 API 安全设计时的速查参考：

安全领域	核心原则	关键要点
认证	明确身份，拒绝匿名	选择适合场景的认证方式；令牌安全存储；HTTPS 传输；短过期时间
授权	最少权限，默认拒绝	合理选择 RBAC/ABAC/ACL 模型；服务端每次请求都校验权限；避免权限越级
限流	保护资源，公平分配	选配合适的限流算法；分多层实施限流；返回标准限流响应头和状态码
审计	可追溯，不可篡改	覆盖敏感操作和异常事件；结构化的日志格式；仅追加存储；设置保存周期
敏感数据保护	全链路加密，最小暴露	TLS 传输加密；字段级存储加密；强哈希存储密码；响应脱敏；前端掩码显示
架构设计	纵深防御，默认安全	多层安全控制；安全组件故障时拒绝访问；白名单输入校验；清晰的信任边界

九、结语

API 安全不是一个可以"一步到位"的目标，而是一项需要持续投入和持续改进的工程实践。在设计之初就将安全内建到 API 的架构中，远比上线后再打补丁要高效且可靠。本文所述的认证、授权、限流、审计和敏感数据保护等实践，构成了 API 安全设计的基础框架，但在实际落地时，仍需结合业务场景、合规要求和团队技术栈进行针对性的调整和深化。

安全设计没有银弹，唯有坚持原则、持续学习、不断迭代，才能在日益复杂的网络环境中守住安全的底线。

参考文献：

OWASP API Security Top 10 (2023)
RFC 7519 - JSON Web Token
RFC 6749 - The OAuth 2.0 Authorization Framework
NIST SP 800-63B - Digital Identity Guidelines
OWASP Cheat Sheet Series - REST Security

API 安全设计原则 ​

一、引言 ​

二、API 安全整体架构与设计原则 ​

2.1 纵深防御架构 ​

2.2 安全设计核心原则 ​

三、认证（Authentication） ​

3.1 API Key ​

3.2 JWT（JSON Web Token） ​

3.3 OAuth2 ​

3.4 Session 认证 ​

3.5 认证方式选型对比 ​

四、授权（Authorization） ​

4.1 RBAC（Role-Based Access Control） ​

4.2 ABAC（Attribute-Based Access Control） ​

4.3 ACL（Access Control List） ​

4.4 选型建议 ​

五、限流（Rate Limiting） ​

5.1 限流算法 ​

5.1.1 令牌桶算法（Token Bucket） ​

5.1.2 漏桶算法（Leaky Bucket） ​

5.1.3 滑动窗口算法（Sliding Window） ​

5.2 分布式限流（Redis 实现） ​

5.3 各层限流策略 ​

5.4 限流响应策略 ​

六、审计（Audit Logging） ​

6.1 审计范围的界定 ​

6.2 审计日志结构 ​

6.3 审计日志存储 ​

七、敏感数据保护 ​

7.1 传输加密（TLS） ​

7.2 存储加密 ​

7.3 数据脱敏 ​

7.4 掩码显示与前端保护 ​

八、原则总结 ​

九、结语 ​

API 安全设计原则

一、引言

二、API 安全整体架构与设计原则

2.1 纵深防御架构

2.2 安全设计核心原则

三、认证（Authentication）

3.1 API Key

3.2 JWT（JSON Web Token）

3.3 OAuth2

3.4 Session 认证

3.5 认证方式选型对比

四、授权（Authorization）

4.1 RBAC（Role-Based Access Control）

4.2 ABAC（Attribute-Based Access Control）

4.3 ACL（Access Control List）

4.4 选型建议

五、限流（Rate Limiting）

5.1 限流算法

5.1.1 令牌桶算法（Token Bucket）

5.1.2 漏桶算法（Leaky Bucket）

5.1.3 滑动窗口算法（Sliding Window）

5.2 分布式限流（Redis 实现）

5.3 各层限流策略

5.4 限流响应策略

六、审计（Audit Logging）

6.1 审计范围的界定

6.2 审计日志结构

6.3 审计日志存储

七、敏感数据保护

7.1 传输加密（TLS）

7.2 存储加密

7.3 数据脱敏

7.4 掩码显示与前端保护

八、原则总结

九、结语