> ## Documentation Index
> Fetch the complete documentation index at: https://docs.killb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳实践

> 生产就绪的集成指南

## 安全

<AccordionGroup>
  <Accordion title="保护凭据" icon="lock">
    * 将 API 密钥存储在环境变量中
    * 永远不要将密钥提交到版本控制
    * 定期轮换密钥
    * 使用密钥管理服务
  </Accordion>

  <Accordion title="验证输入" icon="check">
    * 在客户端验证用户输入
    * 在 API 调用前清理数据
    * 在提交前检查格式
    * 防止注入攻击
  </Accordion>

  <Accordion title="保护 Webhooks" icon="shield">
    * 始终验证签名
    * 仅使用 HTTPS
    * 实施速率限制
    * 记录可疑活动
  </Accordion>
</AccordionGroup>

## 性能

<AccordionGroup>
  <Accordion title="战略性缓存" icon="database">
    * 缓存用户数据（1 小时 TTL）
    * 缓存银行列表（24 小时）
    * 缓存余额（5 分钟）
    * 在 webhooks 上使缓存失效
  </Accordion>

  <Accordion title="优化 API 调用" icon="bolt">
    * 使用 webhooks 而不是轮询
    * 批量相关操作
    * 实现请求去重
    * 对大型数据集使用分页
  </Accordion>

  <Accordion title="优雅地处理错误" icon="triangle-exclamation">
    * 实现重试逻辑
    * 使用指数退避
    * 记录错误以便调试
    * 显示用户友好的消息
  </Accordion>
</AccordionGroup>

## 用户体验

<AccordionGroup>
  <Accordion title="清晰的沟通" icon="comment">
    * 显示确切的金额和费用
    * 显示处理时间
    * 提供状态更新
    * 清楚地解释要求
  </Accordion>

  <Accordion title="渐进式 KYC" icon="stairs">
    * 从 L0/L1 开始
    * 在用户需要更高限额时升级
    * 解释验证的好处
    * 使 KYC 流程顺畅
  </Accordion>

  <Accordion title="处理边缘情况" icon="flask">
    * 报价过期
    * 支付失败
    * 网络问题
    * 慢速交易
  </Accordion>
</AccordionGroup>

## 测试

<AccordionGroup>
  <Accordion title="使用沙盒" icon="vial">
    * 在沙盒中测试所有流程
    * 测试错误场景
    * 测试边缘情况
    * 验证 webhook 处理
  </Accordion>

  <Accordion title="在生产中监控" icon="chart-line">
    * 设置日志记录
    * 跟踪错误率
    * 监控性能
    * 对问题发出警报
  </Accordion>
</AccordionGroup>

## 幂等性

使用 `externalId` 实现幂等性：

```javascript theme={null}
// 防止重试时重复创建 ramp
const createRamp = async (quoteId, userId, accountId, orderId) => {
  return await fetch('/api/v2/ramps', {
    method: 'POST',
    headers: { /* headers */ },
    body: JSON.stringify({
      quotationId: quoteId,
      userId: userId,
      accountId: accountId,
      externalId: `order-${orderId}` // 幂等性密钥
    })
  });
};
```

## 生产清单

<Steps>
  <Step title="安全">
    * [ ] API 密钥在环境变量中
    * [ ] Webhook 签名验证
    * [ ] 仅使用 HTTPS
    * [ ] 输入验证
  </Step>

  <Step title="错误处理">
    * [ ] 已实现重试逻辑
    * [ ] 用户友好的错误消息
    * [ ] 错误日志记录
    * [ ] 监控警报
  </Step>

  <Step title="测试">
    * [ ] 在沙盒中测试所有流程
    * [ ] 已处理边缘情况
    * [ ] Webhook 交付已验证
    * [ ] 负载测试已完成
  </Step>

  <Step title="监控">
    * [ ] 已配置日志记录
    * [ ] 错误跟踪（Sentry 等）
    * [ ] 性能监控
    * [ ] 已设置警报
  </Step>
</Steps>

## 下一步

<Card title="上线" icon="rocket" href="/zh/sandbox">
  从沙盒切换到生产
</Card>