前言：API安全形势严峻

一、认证与授权：守好第一道门

1.1 JWT安全的最佳实践

// ❌ 危险做法1：不验证签名算法
const decoded = jwt.verify(token, secret);
// 攻击者可以伪造任意token

// ❌ 危险做法2：不设置过期时间
jwt.sign({ userId: 123 }, secret);
// token永久有效，一旦泄露无法挽回

// ❌ 危险做法3：使用弱密钥
jwt.sign(payload, 'password123');
// 暴力破解几分钟就能攻破

正确做法：
const jwt = require('jsonwebtoken');

// 1. 使用强密钥（至少256位）
const secret = process.env.JWT_SECRET; // 应该是一个随机生成的32字节字符串

// 2. 始终指定算法
const decoded = jwt.verify(token, secret, {
  algorithms: ['HS256'],  // 只允许指定算法
  issuer: 'your-app-name',  // 验证签发者
  audience: 'your-app-users'  // 验证接收者
});

// 3. 设置合理的过期时间
const token = jwt.sign(
  { userId: user.id, role: user.role },
  secret,
  {
    algorithm: 'HS256',
    expiresIn: '1h',  // 1小时过期
    issuer: 'your-app-name',
    audience: 'your-app-users',
    jwtid: crypto.randomUUID()  // 用于token撤销
  }
);

#
1.2 OAuth 2.0实战


授权码模式流程：
1. 用户点击"登录"
2. 跳转到授权服务器: GET /oauth/authorize?client_id=xxx&redirect_uri=yyy&response_type=code&scope=read
3. 用户授权
4. 授权服务器回调: GET /callback?code=xxx
5. 后端用code换token: POST /oauth/token
6. 获取access_token和refresh_token

Token刷新机制：
// Token即将过期时，用refresh_token换新token
async function refreshAccessToken(refreshToken) {
  try {
    const decoded = jwt.verify(refreshToken, refreshSecret);
    
    // 检查refresh_token是否已撤销
    const isRevoked = await checkRevoked(decoded.jti);
    if (isRevoked) {
      throw new Error('Token has been revoked');
    }
    
    // 生成新的access_token
    const newAccessToken = jwt.sign(
      { userId: decoded.userId },
      accessSecret,
      { expiresIn: '1h' }
    );
    
    return { accessToken: newAccessToken };
  } catch (error) {
    throw new Error('Invalid refresh token');
  }
}

二、输入验证：拦住恶意数据


#
2.1 SQL注入防护


最危险的漏洞之一：
// ❌ 危险做法：直接拼接SQL
const query = 'SELECT * FROM users WHERE id = ' + userId;
// 如果userId = "1 OR 1=1"，后果不堪设想

// ✅ 正确做法1：使用参数化查询
const query = 'SELECT * FROM users WHERE id = $1';
const result = await db.query(query, [userId]);

// ✅ 正确做法2：使用ORM
const user = await User.findById(userId);

// ✅ 正确做法3：输入验证
function validateUserId(id) {
  if (!Number.isInteger(Number(id)) || Number(id) <= 0) {
    throw new ValidationError('Invalid user ID');
  }
  return Number(id);
}

#
2.2 XSS攻击防护


存储型XSS最危险：
// ❌ 危险做法：直接输出用户输入
res.send('
' + user.bio + '
');

// ✅ 正确做法1：HTML转义
const escapeHtml = (str) => {
  const map = {
    '&': '&',
    '<': '<',
    '>': '>',
    '"': '"',
    "'": ''',
    '/': '/'
  };
  return str.replace(/[&<>"'/]/g, char => map[char]);
};

// ✅ 正确做法2：使用模板引擎的自动转义
// EJS、Handlebars等默认转义

// ✅ 正确做法3：Content-Security-Policy头
res.setHeader('Content-Security-Policy', 
  "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';"
);

#
2.3 JSON Schema验证


const Ajv = require('ajv');
const ajv = new Ajv({ allErrors: true });

const userSchema = {
  type: 'object',
  properties: {
    email: { type: 'string', format: 'email' },
    age: { type: 'integer', minimum: 0, maximum: 150 },
    password: { type: 'string', minLength: 8, pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)' }
  },
  required: ['email', 'password'],
  additionalProperties: false
};

const validate = ajv.compile(userSchema);

function validateUser(data) {
  const valid = validate(data);
  if (!valid) {
    return {
      valid: false,
      errors: validate.errors.map(e => ({
        field: e.instancePath || e.params.missingProperty,
        message: e.message
      }))
    };
  }
  return { valid: true };
}

三、速率限制：防止滥用和爬虫


#
3.1 多层限流策略


const rateLimit = require('express-rate-limit');
const Redis = require('ioredis');
const redis = new Redis();

// 1. 全局限流（每人每分钟100次）
const globalLimiter = rateLimit({
  windowMs: 60 * 1000,  // 1分钟
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  keyGenerator: (req) => req.ip,
  handler: (req, res) => {
    res.status(429).json({
      error: {
        code: 'RATE_LIMIT_EXCEEDED',
        message: '请求过于频繁，请稍后再试',
        retry_after: 60
      }
    });
  }
});

// 2. 敏感接口限流（每人每分钟10次）
const sensitiveLimiter = rateLimit({
  windowMs: 60 * 1000,
  max: 10,
  keyGenerator: (req) => req.user?.id || req.ip
});

// 3. IP白名单（开发/运维IP不限流）
const whitelist = ['127.0.0.1', '10.0.0.0/8'];
const whitelistLimiter = rateLimit({
  windowMs: 60 * 1000,
  max: 10000,  // 白名单用户的高限额
  keyGenerator: (req) => req.ip,
  skip: (req) => whitelist.some(ip => req.ip.startsWith(ip))
});

// 应用中间件
app.use(whitelistLimiter);
app.use(globalLimiter);
app.post('/login', sensitiveLimiter, loginHandler);
app.post('/payment', sensitiveLimiter, paymentHandler);

#
3.2 分布式限流（Redis实现）


async function checkRateLimit(userId, action, limit, windowSeconds) {
  const key = `rate_limit:${action}:${userId}`;
  
  const multi = redis.multi();
  multi.incr(key);
  multi.ttl(key);
  
  const [count, ttl] = await multi.exec();
  
  // 首次请求，设置过期时间
  if (ttl === -1) {
    await redis.expire(key, windowSeconds);
  }
  
  // 超出限制
  if (count > limit) {
    const retryAfter = ttl === -1 ? windowSeconds : ttl;
    throw new RateLimitError(retryAfter);
  }
  
  return {
    remaining: Math.max(0, limit - count),
    resetAt: Date.now() + (ttl === -1 ? windowSeconds : ttl) * 1000
  };
}

// 使用示例
async function loginHandler(req, res) {
  const { email, password } = req.body;
  
  try {
    // 登录限流：每分钟5次
    const limitInfo = await checkRateLimit(
      email, 'login', 5, 60
    );
    
    res.set({
      'X-RateLimit-Limit': 5,
      'X-RateLimit-Remaining': limitInfo.remaining,
      'X-RateLimit-Reset': limitInfo.resetAt
    });
    
    // 执行业务逻辑...
  } catch (error) {
    if (error instanceof RateLimitError) {
      return res.status(429).json({
        error: {
          code: 'RATE_LIMIT_EXCEEDED',
          message: '登录尝试次数过多，请稍后再试',
          retry_after: error.retryAfter
        }
      });
    }
    throw error;
  }
}

四、CORS配置：跨域安全


#
4.1 安全CORS配置


// ❌ 危险配置：允许所有来源
app.use(cors({
  origin: '*',  // 极度危险！
  credentials: true
}));

// ✅ 安全配置
const corsOptions = {
  // 生产环境：只允许自己的域名
  origin: process.env.NODE_ENV === 'production'
    ? ['https://524900.xyz', 'https://www.524900.xyz']
    : ['http://localhost:3000'],
  
  // 允许携带凭证（cookies、Authorization头）
  credentials: true,
  
  // 只允许需要的HTTP方法
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
  
  // 只允许需要的请求头
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
  
  // 暴露给前端的响应头
  exposedHeaders: ['X-Total-Count', 'X-Page-Count'],
  
  // 预检请求缓存时间
  maxAge: 86400  // 24小时
};

app.use(cors(corsOptions));

#
4.2 动态CORS（支持多域名）


const allowedOrigins = [
  'https://524900.xyz',
  'https://www.524900.xyz',
  'https://app.524900.xyz',
  'https://admin.524900.xyz'
];

app.use(cors({
  origin: (origin, callback) => {
    // 允许没有origin的请求（如Postman测试）
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('不允许的来源: ' + origin));
    }
  },
  credentials: true
}));

五、安全响应头：多一层保护


#
5.1 关键安全头配置


const helmet = require('helmet');

// 使用helmet自动设置安全头
app.use(helmet());

// 自定义配置
app.use(helmet({
  // 防止点击劫持
  frameguard: { action: 'deny' },
  
  // 启用严格传输安全（HTTPS）
  hsts: {
    maxAge: 31536000,  // 1年
    includeSubDomains: true,
    preload: true
  },
  
  // 禁用X-Powered-By头
  noSniff: true,
  
  // XSS防护
  xssFilter: true,
  
  // 防止IE下载执行恶意文件
  ieNoOpen: true
}));

// 额外的安全配置
app.use((req, res, next) => {
  // 防止CSP泄露
  res.removeHeader('X-Powered-By');
  
  // 内容类型嗅探保护
  res.setHeader('X-Content-Type-Options', 'nosniff');
  
  // X-Frame-Options
  res.setHeader('X-Frame-Options', 'DENY');
  
  // X-XSS-Protection
  res.setHeader('X-XSS-Protection', '1; mode=block');
  
  // Referrer Policy
  res.setHeader('Referrer-Policy', 'strict-origin-when-cross-origin');
  
  // Permissions Policy
  res.setHeader('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
  
  next();
});

六、敏感数据保护


#
6.1 数据脱敏


function maskSensitiveData(data, fields) {
  const masked = { ...data };
  
  for (const field of fields) {
    if (masked[field]) {
      const value = String(masked[field]);
      const len = value.length;
      
      if (len <= 4) {
        masked[field] = '';
      } else if (field.includes('phone')) {
        // 手机号：只显示后4位
        masked[field] = '' + value.slice(-4);
      } else if (field.includes('idcard') || field.includes('card')) {
        // 身份证/银行卡：只显示后4位
        masked[field] = value.slice(0, 4) + '' + value.slice(-4);
      } else if (field.includes('email')) {
        // 邮箱：只显示前两位和域名
        const [local, domain] = value.split('@');
        masked[field] = local.slice(0, 2) + '***@' + domain;
      } else {
        // 默认：只显示前后各2位
        masked[field] = value.slice(0, 2) + '' + value.slice(-2);
      }
    }
  }
  
  return masked;
}

// 使用示例
const safeUserData = maskSensitiveData(user, [
  'phone', 'email', 'idcard', 'bankcard', 'password', 'secret'
]);

#
6.2 日志脱敏


const sensitiveFields = ['password', 'token', 'secret', 'apiKey', 'creditCard'];

function sanitizeForLog(data) {
  if (typeof data !== 'object' || data === null) {
    return data;
  }
  
  const sanitized = Array.isArray(data) ? [] : {};
  
  for (const [key, value] of Object.entries(data)) {
    if (sensitiveFields.some(f => key.toLowerCase().includes(f))) {
      sanitized[key] = '[REDACTED]';
    } else if (typeof value === 'object') {
      sanitized[key] = sanitizeForLog(value);
    } else {
      sanitized[key] = value;
    }
  }
  
  return sanitized;
}

// 使用
console.log('Request:', sanitizeForLog(req.body));
// 输出: Request: { email: '[email protected]', password: '[REDACTED]' }

七、API安全监控与告警


#
7.1 异常行为检测


class SecurityMonitor {
  constructor() {
    this.failedAttempts = new Map();
    this.suspiciousIPs = new Set();
  }
  
  // 检测暴力破解
  async checkBruteForce(ip) {
    const attempts = this.failedAttempts.get(ip) || 0;
    const now = Date.now();
    
    // 5分钟内失败超过5次
    if (attempts >= 5) {
      this.suspiciousIPs.add(ip);
      await this.sendAlert({
        type: 'BRUTE_FORCE',
        ip,
        attempts,
        timestamp: now
      });
      return true;
    }
    
    this.failedAttempts.set(ip, attempts + 1);
    
    // 10分钟后清除记录
    setTimeout(() => {
      const current = this.failedAttempts.get(ip);
      if (current) {
        this.failedAttempts.set(ip, Math.max(0, current - 1));
      }
    }, 10 * 60 * 1000);
    
    return false;
  }
  
  // 检测异常请求模式
  async checkSuspiciousPattern(req) {
    // 检测扫描行为（短时间内请求大量404）
    const pathCount = await redis.incr(`scan_detect:${req.ip}`);
    await redis.expire(`scan_detect:${req.ip}`, 60);
    
    if (pathCount > 50) {  // 1分钟内请求50+个路径
      await this.sendAlert({
        type: 'PATH_SCANNING',
        ip: req.ip,
        paths: pathCount,
        timestamp: Date.now()
      });
      return true;
    }
    
    return false;
  }
  
  async sendAlert(alert) {
    // 发送到告警系统（钉钉、企业微信、邮件等）
    console.error('Security Alert:', JSON.stringify(alert));
    // await sendToDingTalk(alert);
  }
}

八、安全开发流程


#
8.1 API安全检查清单


发布前必查：
- [ ] 所有接口都有认证检查
- [ ] 权限验证覆盖所有敏感操作
- [ ] 输入参数全部验证
- [ ] SQL使用参数化查询
- [ ] 敏感数据加密存储
- [ ] 安全响应头已配置
- [ ] 速率限制已实施
- [ ] 错误信息不泄露敏感细节
- [ ] 日志不记录密码/Token
- [ ] CORS配置正确
- [ ] HTTPS已启用
- [ ] 依赖包无已知漏洞

#
8.2 定期安全审计


# 1. 依赖包漏洞扫描
npm audit
npm audit fix

# 2. OWASP ZAP自动化扫描
docker run -t owasp/zap2docker-stable zap-api-scan.py   -t http://localhost:3000/api-docs   -f openapi

# 3. 代码审计
npx eslint --rule 'no-eval: error' src/
npx eslint --rule 'no-new-func: error' src/

结语


API安全是一场持久战，没有银弹。根据《2025年数据泄露成本报告》，数据泄露的平均成本已经达到488万美元，远超安全投入。作为开发者，我们必须：

1. 安全意识常态化 - 每次代码提交都要考虑安全影响
2. 纵深防御 - 多层保护，一层被突破还有下一层
3. 持续监控 - 及时发现异常，快速响应
4. 定期审计 - 定期检查，及时修复漏洞

在Free API Hub，我们不仅提供免费的API接口，还致力于传播安全开发的理念。希望本文能帮助你构建更安全的API系统。

---

延伸阅读：
- [REST API设计最佳实践2026](/blog/rest-api-design-best-practices-2026)
- [API错误处理最佳实践](/blog/api-error-handling-best-practices)