---

name: api-security-best-practices description: "实现安全的 API 设计模式，包括认证、授权、输入验证、速率限制以及常见 API 漏洞防护" risk: unknown source: community date_added: "2026-02-27"

API 安全最佳实践

概述

指导开发者通过实现认证、授权、输入验证、速率限制和常见漏洞防护来构建安全的 API。本技能涵盖 REST、GraphQL 和 WebSocket API 的安全模式。

何时使用此技能

• 设计新的 API 端点时使用
• 加固现有 API 安全时使用
• 实现认证和授权时使用
• 防御 API 攻击（注入、DDoS 等）时使用
• 进行 API 安全审查时使用
• 准备安全审计时使用
• 实现速率限制和节流时使用
• 在 API 中处理敏感数据时使用

工作原理

第 1 步：认证与授权

我将帮助你实现安全的认证：

• 选择认证方式（JWT、OAuth 2.0、API 密钥）
• 实现基于令牌的认证
• 设置基于角色的访问控制（RBAC）
• 安全的会话管理
• 实现多因素认证（MFA）

第 2 步：输入验证与清理

防御注入攻击：

• 验证所有输入数据
• 清理用户输入
• 使用参数化查询
• 实现请求 schema 验证
• 防止 SQL 注入、XSS 和命令注入

第 3 步：速率限制与节流

防止滥用和 DDoS 攻击：

• 实现按用户/IP 的速率限制
• 设置 API 节流
• 配置请求配额
• 优雅地处理速率限制错误
• 监控可疑活动

第 4 步：数据保护

保护敏感数据：

• 传输中加密（HTTPS/TLS）
• 静态敏感数据加密
• 实现正确的错误处理（无数据泄露）
• 清理错误消息
• 使用安全响应头

第 5 步：API 安全测试

验证安全实现：

• 测试认证和授权
• 执行渗透测试
• 检查常见漏洞（OWASP API Top 10）
• 验证输入处理
• 测试速率限制

示例

示例 1：实现 JWT 认证

## 安全的 JWT 认证实现

### 认证流程

1. 用户使用凭据登录
2. 服务器验证凭据
3. 服务器生成 JWT 令牌
4. 客户端安全存储令牌
5. 客户端每次请求携带令牌
6. 服务器验证令牌

### 实现

#### 1. 生成安全的 JWT 令牌

\`\`\`javascript
// auth.js
const jwt = require('jsonwebtoken');
const bcrypt = require('bcrypt');

// Login endpoint
app.post('/api/auth/login', async (req, res) => {
  try {
    const { email, password } = req.body;

    // Validate input
    if (!email || !password) {
      return res.status(400).json({
        error: 'Email and password are required'
      });
    }

    // Find user
    const user = await db.user.findUnique({
      where: { email }
    });

    if (!user) {
      // Don't reveal if user exists
      return res.status(401).json({
        error: 'Invalid credentials'
      });
    }

    // Verify password
    const validPassword = await bcrypt.compare(
      password,
      user.passwordHash
    );

    if (!validPassword) {
      return res.status(401).json({
        error: 'Invalid credentials'
      });
    }

    // Generate JWT token
    const token = jwt.sign(
      {
        userId: user.id,
        email: user.email,
        role: user.role
      },
      process.env.JWT_SECRET,
      {
        expiresIn: '1h',
        issuer: 'your-app',
        audience: 'your-app-users'
      }
    );

    // Generate refresh token
    const refreshToken = jwt.sign(
      { userId: user.id },
      process.env.JWT_REFRESH_SECRET,
      { expiresIn: '7d' }
    );

    // Store refresh token in database
    await db.refreshToken.create({
      data: {
        token: refreshToken,
        userId: user.id,
        expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
      }
    });

    res.json({
      token,
      refreshToken,
      expiresIn: 3600
    });

  } catch (error) {
    console.error('Login error:', error);
    res.status(500).json({
      error: 'An error occurred during login'
    });
  }
});
\`\`\`

#### 2. 验证 JWT 令牌（中间件）

\`\`\`javascript
// middleware/auth.js
const jwt = require('jsonwebtoken');

function authenticateToken(req, res, next) {
  // Get token from header
  const authHeader = req.headers['authorization'];
  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN

  if (!token) {
    return res.status(401).json({
      error: 'Access token required'
    });
  }

  // Verify token
  jwt.verify(
    token,
    process.env.JWT_SECRET,
    {
      issuer: 'your-app',
      audience: 'your-app-users'
    }
  );
}
\`\`\`