用于宠物项目的 API 密钥：HMAC 和缓存

免费开源项目API：自包含密钥与速率限制

若无使用限制，任何人都可能通过垃圾请求淹没系统，迅速耗尽资源。核心策略是什么？减少数据库查询，并在解析阶段过滤无效密钥。

密钥是自包含的，格式为 ppk_version_userId_nonce_signature。认证方式为：Authorization: PetProjects ppk_v1_1_nonce_signature。

验证分为两步：

• 本地验证：不接触数据库，仅检查结构和HMAC签名。
• 数据库查询：仅在初始有效性确认后，才查找userId。

function validateApiKey(apiKey: string): ApiKeyPayload | null {
    if (!apiKey.startsWith('ppk_')) return null;

    const parts = apiKey.split('_');
    if (parts.length !== 5) return null;

    const [, version, userIdRaw, nonce, signature] = parts;

    const userId = Number(userIdRaw);
    if (!Number.isInteger(userId)) return null;

    if (!signature || !/^[a-f0-9]{64}$/.test(signature)) return null;

    const payload = `${version}.${userId}.${nonce}`;

    const expectedSignature = crypto.createHmac('sha256', API_KEY_SECRET).update(payload).digest('hex');

    if (signature.length !== expectedSignature.length) return null;

    const isValid = crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expectedSignature, 'hex'));

    if (!isValid) return null;

    return { version, userId, nonce };
}

timingSafeEqual 可防止时序攻击。有效密钥将缓存于 LRUCache（最大10,000条，TTL 5分钟）。

缓存与性能平衡

缓存可显著降低延迟并减轻数据库压力。5分钟的TTL是一种权衡：一旦密钥泄露，仍可继续使用直至过期，之后需重新验证。

局限性：

• 无法即时撤销密钥。
• 泄露密钥将持续有效至TTL结束。
• 秘钥必须妥善保护。

潜在改进方向：黑名单支持、密钥版本管理、动态撤销机制。

API测试沙盒环境

提供交互式界面，可在浏览器中直接发送请求，密钥自动填充。同时生成多语言代码示例。

示例 POST 请求：

curl -L -X POST 'https://api.pet-projects.io/rest/free' \
-H 'Authorization: PetProjects ppk_v1_1_a1b2c3d4e5_a1b2c3d4e5f6g7h8i10j11' \
-H 'Content-Type: application/json' \
-d '{"hello":"world"}'

响应采用 JSend 标准格式：

{
    "status": "success",
    "data": {
        "id": 99,
        "payload": {
            "hello": "world"
        },
        "createdAt": 1774297745939,
        "updatedAt": 1774297745939
    }
}

扩展性与未来优化方向

该系统最大限度减少数据库调用，抵御滥用行为，在安全与性能间取得良好平衡。随着流量增长，监控缓存命中率与密钥使用情况将成为关键。

对中级及以上开发者的优势：

• 使用真实接口而非模拟数据。
• 无需部署即可上传个人数据。
• 快速HMAC验证 + 缓存机制。
• 内置调试沙盒环境。
• 基于Docker架构，易于横向扩展。

核心要点：

• 自包含密钥可在不访问数据库的情况下过滤99%的无效请求。
• 使用5分钟TTL的LRUCache，使数据库负载降低超90%。
• timingSafeEqual 有效防范时序攻击。
• 两步验证机制：先本地校验，再数据库查证。
• JSend响应格式统一了API行为标准。

— Editorial Team