# Cloudflare 开发最佳实践 ## 概述该技能为在 Cloudflare 边缘平台上开发应用程序提供了全面的指南，包括 Workers、Pages、KV 存储、D1 数据库、R2 对象存储和持久对象。 ## 核心原则 * 编写针对边缘执行而优化的轻量级、快速代码 * 最小化冷启动时间和执行持续时间 * 针对每个用例使用适当的存储解决方案 * 遵循边缘计算的安全最佳实践 * 利用 Cloudflare 的全球网络来提高性能 ## Cloudflare 工作人员指南 ### 基本工人结构导出默认值{ 异步获取（请求：请求，环境：环境，ctx：ExecutionContext）：Promise { 尝试{ const url = 新 URL(request.url); // 路由处理 if (url.pathname === '/api/data') { 返回handleApiRequest（请求，环境）； } 返回新响应（'未找到'，{状态：404}）； } 捕获（错误）{ console.error('工作错误：', error); return new Response('内部服务器错误', { status: 500 }); } }, } 满足 ExportedHandler; ### 环境类型接口环境{ // KV 命名空间 MY_KV: KV命名空间； // D1 数据库 MY_DB：D1数据库； // R2 桶 MY_BUCKET：R2Bucket； // 持久对象 MY_DURABLE_OBJECT：DurableObject命名空间； // 环境变量 API_KEY：字符串； } ### 最佳实践 * 使用 TypeScript 来保证类型安全 * 适当处理边缘错误 * 实施正确的请求验证 * 使用`ctx.waitUntil()`进行后台任务 * 尽可能减少外部 API 调用 ## 牧马人配置 ### wrangler.toml 结构名称 =“我的工人” 主要=“src/index.ts” 兼容性_日期=“2024-01-01” [变量] 环境=“生产” [[kv_命名空间]] 绑定=“MY_KV” id =“abc123” [[d1_数据库]] 绑定=“MY_DB” 数据库名称=“我的数据库” 数据库ID =“def456” [[r2_buckets]] 绑定=“MY_BUCKET” Bucket_name = “我的存储桶” [耐用对象] 绑定 = [ { 名称 =“MY_DURABLE_OBJECT”，class_name =“MyDurableObject”} ] [[迁移]] 标签=“v1” new_classes = ["MyDurableObject"] ## KV 存储指南 ### 使用模式 // 写入KV 等待 env.MY_KV.put('key', JSON.stringify(data), { expiryTtl: 3600, // 1 小时元数据：{版本：'1.0'}， }); // 从KV读取 const value = wait env.MY_KV.get('key', { type: 'json' }); // 列出键 const list = wait env.MY_KV.list({ 前缀: '用户:' }); ### 最佳实践 * 将 KV 用于具有最终一致性的读取密集型工作负载 * 为缓存数据设置适当的TTL * 使用元数据获取额外的关键信息 * 实现缓存失效策略 * 注意KV的最终一致性模型 ## D1 数据库指南 ### 查询模式 // 参数化查询（防止SQL注入）常量结果 = 等待 env.MY_DB .prepare('从用户中选择*，其中 id = ?') .bind(用户ID) .all(); // 批量操作 const 批处理 = 等待 env.MY_DB.batch([ env.MY_DB.prepare('插入日志(消息)值(?)').bind('log1'), env.MY_DB.prepare('插入日志(消息)值(?)').bind('log2'), ]); // 仅第一个结果 const 用户 = 等待 env.MY_DB .prepare('从用户中选择*，其中电子邮件=？') .bind(电子邮件) .first(); ### 模式管理 -- 迁移/0001_initial.sql 创建表用户（ id 整数主键自动增量，电子邮件文本唯一不为空，名称文本不为空，创建时间 DATETIME 默认 CURRENT_TIMESTAMP ）；在用户（电子邮件）上创建索引 idx_users_email； ### 最佳实践 * 始终使用参数化查询 * 创建适当的索引 * 使用批量操作进行多次写入 * 保持查询简单高效 * 使用迁移进行架构更改 ## R2 对象存储指南 ### 使用模式 // 上传对象等待 env.MY_BUCKET.put('uploads/file.pdf', fileData, { http元数据：{ contentType: '应用程序/pdf', }, 自定义元数据：{ 上传者：用户ID， }, }); // 下载对象 const object = wait env.MY_BUCKET.get('uploads/file.pdf'); 如果（对象）{ 返回新的响应（对象.body，{ 标题：{ '内容类型'：object.httpMetadata?.contentType || '应用程序/八位字节流', }, }); } // 列出对象 const list = wait env.MY_BUCKET.list({ 前缀: 'uploads/' }); // 删除对象等待 env.MY_BUCKET.delete('uploads/file.pdf'); ### 最佳实践 * 设置适当的内容类型 * 对大文件使用分段上传 * 实施适当的访问控制 * 使用预签名 URL 进行直接客户端上传 * 用逻辑前缀组织对象 ## 耐用物品指南 ### 实施导出类 ChatRoom 实现 DurableObject { 私有状态：DurableObjectState；私有会话：Map; 构造函数（状态：DurableObjectState，env：Env）{ this.state = 状态； this.sessions = new Map(); } 异步获取（请求：请求）：Promise { const url = 新 URL(request.url); if (url.pathname === '/websocket') { constpair = new WebSocketPair(); 等待 this.handleSession(pair[1]); 返回新的 Response(null, { status: 101, webSocket:pair[0] }); } 返回新响应（'未找到'，{状态：404}）； } 异步handleSession（webSocket：WebSocket）{ webSocket.accept(); webSocket.addEventListener('消息', async (事件) => { // 处理消息 }); webSocket.addEventListener('关闭', () => { this.sessions.delete(webSocket); }); } } ### 最佳实践 * 用于协调和状态逻辑 * 实施正确的 WebSocket 处理 * 使用存储API进行持久化 * 处理休眠以优化成本 * 单点协调模式设计 ## Cloudflare 页面指南 ### 项目结构我的页面项目/ ├── public/ # 静态资产 ├── 函数/ # 页函数 │ ├── API/ │ │ └── [端点].ts │ └── _middleware.ts ├── src/ # 应用源 └── wrangler.toml # 配置 ### 页面功能 // 函数/api/user.ts 导出 const onRequestGet: PagesFunction = async (context) => { const 用户 = 等待 context.env.MY_DB .prepare('从用户中选择*') .all(); 返回 Response.json(users.results); }; 导出 const onRequestPost: PagesFunction = async (context) => { const body =等待context.request.json(); // 处理 POST 返回 Response.json({ 成功: true }); }; ## 边缘安全最佳实践 ### 请求验证函数 validateRequest(请求：请求): 布尔值 { // 检查内容类型 const contentType = request.headers.get('Content-Type'); if (request.method === 'POST' && !contentType?.includes('application/json')) { 返回假； } // 检查来源 (CORS) const origin = request.headers.get('Origin'); if (origin && !ALLOWED_ORIGINS.includes(origin)) { 返回假； } 返回真； } ### 身份验证异步函数 verifyAuth(request: Request, env: Env): Promise { const authHeader = request.headers.get('授权'); if (!authHeader?.startsWith('Bearer ')) { 返回假； } const token = authHeader.slice(7); // 验证 JWT 或 API 密钥返回等待 verifyToken(token, env); } ### 速率限制异步函数 checkRateLimit(ip: string, env: Env): Promise { const key = `ratelimit:${ip}`; const current = wait env.MY_KV.get(key, { type: 'json' }) as number || 0; if (current >= 100) { // 每个窗口 100 个请求返回假； } 等待 env.MY_KV.put(key, JSON.stringify(当前 + 1), { expirationTtl: 60, // 1 分钟窗口 }); 返回真； } ## 性能优化 ### 缓存策略 // 缓存API使用 const 缓存 = 缓存.默认值; 异步函数handleRequest（请求：请求）：Promise { // 检查缓存 const 缓存 = 等待缓存.match(请求); 如果（缓存）{ 返回缓存； } // 生成响应 const 响应 = 等待生成响应（请求）； // 缓存响应 const cacheResponse = new Response(response.body, 响应); cacheResponse.headers.set('Cache-Control', 'public, max-age=3600'); ctx.waitUntil(cache.put(请求,cacheResponse.clone())); 返回缓存响应； } ### 后台处理导出默认值{ 异步获取（请求：请求，环境：环境，ctx：ExecutionContext）：Promise { // 立即响应 const response = Response.json({ status: '已接受' }); // 后台进程 ctx.waitUntil(processInBackground(请求, env)); 返回响应； }, }; ## 测试 ### 本地发展 # 启动本地开发服务器牧马人开发者 # 使用本地持久性运行牧马人开发——坚持 # 使用特定环境进行测试牧马人开发--env 登台 ### 单元测试从“牧马人”导入{unstable_dev}；描述('工人', () => { 让工作人员：UnstableDevWorker； beforeAll(异步() => { 工人 = 等待不稳定_dev('src/index.ts', { 实验：{disableExperimentalWarning：true}， }); }); 毕竟（异步（）=> { 等待worker.stop(); }); test('有效请求返回 200', async () => { const response =等待worker.fetch('/api/health'); 期望(响应.状态).toBe(200); }); }); ## 部署 ### 生产部署 # 部署到生产环境牧马人部署 # 部署到特定环境牧马人部署 --env 生产 # 使用秘密进行部署牧马人秘放 API_KEY ### CI/CD 集成 # .github/workflows/deploy.yml 名称：部署工作人员于：推：分支：[主要] 职位：部署：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v4 - 使用：cloudflare/wrangler-action@v3 与： apiToken：${{secrets.CLOUDFLARE_API_TOKEN}} ## 要避免的常见陷阱 1. 没有正确处理边缘错误 2. 外部API调用过多 3.忽略Worker CPU和内存限制 4. 未针对用例使用适当的存储 5. 忘记 KV 中的最终一致性 6. 没有实施适当的速率限制 7. 在代码中硬编码秘密 8.忽略冷启动优化

Cloudflare 开发

包含技能